Claude Agent SDK Master

Claude Agent SDK Master

🎓 从零到一掌握 Claude Agent SDK 的渐进式学习教程

快速开始 • 学习路线 • 项目结构 • 核心理念 • 相关资源

💡 项目定位

Claude Agent SDK Master 是一个渐进式学习教程系列，作为 Proma 开源项目的前奏和技术基础，旨在：

• 🎯 帮助开发者系统掌握 Claude Agent SDK 的核心概念和高级特性
• 🔨 通过实际可运行的项目理解 Agent 状态管理和用户体验转换
• 🌟 为开源社区提供高质量的 Agent SDK 中文学习资源
• 🚀 培养 AI 原生应用开发思维，为 Proma 等项目贡献做准备

🤔 为什么需要这个教程？

Agent SDK 的潜力远超目前的开发程度。即便 Claude 官方的 Claude Code 和 Cowork，可能也只触及了 SDK 能力的 10%。

Agent SDK 的应用空间巨大，但相比单纯套用 LLM API 以及其他需要进行编排的 Agents 而言，它要求你：

• 深入理解状态管理和流式响应机制
• 重新设计用户体验和交互模式
• 掌握更复杂的嵌套状态和工具调用逻辑

本教程的使命：让你真正理解 Agent SDK 的设计，并能优雅地应用这些状态。

项目赞助商 MiniMax

本教程推荐采用 MiniMax API 更丝滑更具性价比的完成 Claude Agent SDK 的学习，全面兼容所有功能(订阅 Coding Plan 一样可以生成 Coding Plan api key 来学习和应用到本教程)

MiniMax api 获取和注册地址，还可领取 88 折的优惠！：https://platform.minimaxi.com/subscribe/coding-plan?code=cVcgRF3hAQ&source=link

📖 学习路线

本系列采用渐进式学习路径，每一章在前一章基础上递进，建议按顺序学习：

💡 提示：本教程随 Proma 实际开发进度持续更新。

⚡ 快速开始

前置要求

• Node.js 18+
• pnpm 包管理器（推荐）
• Anthropic API Key（推荐MiniMax API 即可） 点击获取 minimax api key（也可以是支持 Anthropic /v1/messages 的其他 api）

三步开始学习

# 1️⃣ 克隆仓库
git clone https://github.com/ErlichLiu/claude-agent-sdk-master.git
cd claude-agent-sdk-master

# 2️⃣ 进入第一章教程
cd 01-quick-start

# 3️⃣ 安装依赖
pnpm install

# 4️⃣ 配置 API Key
cp .env.local.example .env.local
# 编辑 .env.local，填入你的 ANTHROPIC_API_KEY 以及可选的 ANTHROPIC_BASE_URL

# 5️⃣ 启动开发服务器
pnpm dev

访问 http://localhost:3000，开始你的 Agent SDK 学习之旅！🎉

🎮 从 00-Playground 开始（推荐）

如果你想快速体验 Agent SDK 的核心功能，推荐先从 00-Playground 开始：

# 进入 00-playground 目录
cd 00-playground

# 安装依赖
pnpm install

# 配置 API Key
cp .env.example .env.local
# 编辑 .env.local，填入你的 ANTHROPIC_API_KEY

# 启动交互式测试
pnpm play

Playground 的优势：

• 📝 核心代码精简：playground.ts 只有 ~120 行，专注于 SDK 调用
• ⚡ 即时反馈：修改代码后立即运行查看效果
• 🔧 交互式配置：通过命令动态切换工具、输出模式等
• 🎯 零 UI 干扰：纯命令行，专注理解 SDK 机制

适合想要快速修改代码、理解 SDK 行为的开发者。详见 Playground README。

📂 项目结构

claude-agent-sdk-master/
│
├── 00-playground/              # 🎮 SDK 交互式测试环境（推荐入门）
│   ├── playground.ts        #    核心 SDK 调用代码
│   ├── lib/                 #    配置和 CLI 模块
│   └── utils/               #    打印输出工具
│
├── 01-quick-start/          # 🚀 第一章：快速入门
│   ├── app/                 #    Next.js App Router
│   ├── components/          #    UI 组件（三栏布局、Markdown 等）
│   ├── lib/storage/         #    JSONL 文件存储实现
│   ├── packages/core/       #    核心类型定义（Monorepo）
│   ├── README.md            #    详细教程文档
│   └── CLAUDE.md            #    Claude Code 开发指引
│
├── 02-tools-and-mcp/        # 🔧 第二章：工具与 MCP
│   ├── app/                 #    Next.js App Router + API Routes
│   ├── components/          #    工具活动可视化组件
│   ├── packages/shared/     #    PromaAgent 事件驱动架构
│   ├── packages/core/       #    核心类型定义
│   └── CLAUDE.md            #    开发指引
│
├── 03-agent-with-permission/ # 🔐 第三章：Agent 权限控制
│   ├── app/                 #    权限审批 API + 聊天 API
│   ├── components/          #    权限审批 UI 组件
│   ├── packages/shared/     #    canUseTool 权限回调
│   └── CLAUDE.md            #    开发指引
│
├── 04-agent-teams/          # 🤝 第四章：Agent Teams 多 Agent 协作
│   ├── app/                 #    Teams API + Chat API（Auto-Resume）
│   ├── components/          #    TeammateCard、详情面板
│   ├── packages/shared/     #    PromaAgent + Agent Teams 事件
│   ├── lib/                 #    AgentTeamStore 状态管理
│   └── CLAUDE.md            #    开发指引
│
└── README.md                # 📖 本文件（系列教程总览）

🎯 核心理念

软件的本质，归根结底是对状态的优雅处理。

这是贯穿本系列教程的核心哲学。无论是：

• Claude Agent SDK 的 Session 状态
• React 的 组件状态
• Proma 的 应用状态

掌握状态的本质，你就能理解现代软件开发的精髓。

✨ 教程特色

• 📚 体系完整：从基础到高级，覆盖 Agent SDK 完整能力
• 🔄 渐进式学习：每章在前一章基础上递进，循序渐进
• 💻 实战导向：每章都是可运行的完整项目，边学边练
• 📖 详细文档：每个项目配备详尽的 README 和 CLAUDE.md 开发指引
• 🤖 AI 协作实践：大部分内容由 Claude Code 编写，展示 AI 辅助开发最佳实践
• 🇨🇳 中文优先：高质量中文技术文档，降低学习门槛

技术栈

• Claude Agent SDK v0.2.68+ · 默认模型 claude-sonnet-4-6
• Next.js 16 (App Router) · React 19 · TypeScript 5 (strict)
• Tailwind CSS 4 · Shadcn UI · framer-motion
• pnpm workspace monorepo（02-04 章）

🔗 相关资源

官方文档

• Claude Agent SDK 官方文档 - TypeScript SDK 官方指南
• Anthropic API 文档 - Claude API 完整文档
• MiniMax API 文档 - MiniMax API 完整文档

相关项目

• Proma - 基于 Agent SDK 的完整开源产品（即将发布）
• Claude Code - Anthropic 官方代码编辑器
• MCP Servers - Model Context Protocol 服务端实现
• Craft Agent OSS - 本项目设计参考，推荐学习

技术栈

• Next.js 文档 - App Router 完整指南
• Shadcn UI - UI 组件库
• Tailwind CSS - 原子化 CSS 框架

🤝 贡献

欢迎提交 Issue 和 Pull Request！如果这个项目对你有帮助：

• ⭐ Star 本项目 - 让更多人看到这个教程
• 🐛 报告 Bug - 发现问题请提 Issue
• 📖 完善文档 - 发现错误或有改进建议欢迎 PR
• 💡 分享经验 - 在 Discussion 中分享你的学习心得
• 🚀 贡献到 Proma - 学完本教程后欢迎为 Proma 项目做贡献

如何贡献

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的改动 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启一个 Pull Request

❓ 常见问题

Q: 我需要什么基础知识？

• 必需：JavaScript/TypeScript 基础、React 基础
• 推荐：Next.js 了解、异步编程经验
• 加分项：有使用过 LLM API 的经验

Q: Agent SDK 和直接调用 Claude API 有什么区别？

Agent SDK 提供了更高层的抽象：

• 自动上下文管理：不需要手动拼接 messages
• 文件系统集成：Agent 可以读写本地文件
• 工具调用封装：内置 Tool Calling 和 MCP 支持
• 会话持久化：自动存储对话历史

适合构建持久化、有状态的 AI 应用，而不是简单的问答。

Q: 为什么选择 Next.js？

• App Router：原生支持 Server Actions 和流式响应
• 全栈能力：API Routes 便于构建后端逻辑
• 开发体验：热重载、TypeScript 支持、现代工具链
• 生态丰富：与 Shadcn UI、Tailwind CSS 等无缝集成

当然，你也可以将 Agent SDK 集成到任何 Node.js 框架和 Python 框架中，并不代表在正式生产项目上采用 NextJS。

Q: 这个教程会持续更新吗？

是的！本教程随 Proma 项目的开发进度持续更新：

• ✅ 第一章已完成（快速入门）
• ✅ 第二章已完成（工具与 MCP）
• ✅ 第三章已完成（权限控制）
• ✅ 第四章已完成（Agent Teams）

关注本仓库获取最新更新通知。

📄 License

MIT License - 自由使用，欢迎改进和分享

Star History


🎓 开始学习： 第一章：快速入门

本教程由 Claude Code 协助创建 ✨

随 Proma 开发进度持续更新

如果对你有帮助，欢迎 Star ⭐️