词元之母TOK.MOM - 平台充值汇率 1:1 即 1 人民币充值到账 1 美元，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
09-Agent-SDK完整指南
Claude Agent SDK 完整指南：把AI编程能力装进你的程序里
课程信息 预计学时：6-8小时 难度等级：⭐⭐⭐ 中级进阶 更新日期：2026年4月 适用版本：Claude Code v2.1.133（验证于 2026-05-08）
版本说明：Claude Agent SDK（原名Claude Code SDK）是2025年Anthropic官方发布的开发工具包。本教程基于最新官方文档编写，如有更新请以官方为准。
本课学习目标
1.
2.
3.
4.
5.
6.
学习路径导航（先看这里！）
这是一篇长教程，不用全看！根据你的目标选择路径。
路径A：快速体验（60分钟）
术语表（5分钟）
第一部分：SDK简介（10分钟）
第二部分：5分钟快速开始（20分钟）
实战项目1：Hello World Agent（25分钟）路径B：系统学习（6-8小时）
路径C：问题速查（5分钟）
第六部分：故障排查 - 按错误类型查找解决方案
第七部分：FAQ - 20个精选问题路径D：专项学习（30-60分钟/主题）
| 想学什么 | 看哪几节 | 预计时间 |
|---|---|---|
| 自定义工具 | 第三部分3.3节 + 第四部分项目3 | 60分钟 |
| Hooks钩子 | 第五部分5.2节 | 45分钟 |
| 子代理并行 | 第三部分3.4节 + 第四部分项目3 | 60分钟 |
| MCP集成 | 第五部分5.1节 | 45分钟 |
术语表（小白必读）
| 术语 | 英文全称 | 通俗解释 |
|---|---|---|
| SDK | Software Development Kit | 软件开发工具包，就像一个"工具箱"，里面有各种你需要的零件和工具，让你能更方便地造东西 |
| Agent | - | 智能代理/自动机器人，能够自主完成任务的AI程序。就像一个会思考的机器人助手，你给它任务，它自己想办法完成 |
| Agent Loop | - | 代理循环，Agent工作的核心流程：接收任务→思考→使用工具→检查结果→继续或结束。就像一个"工作循环" |
| Tool | - | 工具，Agent可以调用的能力，比如读文件、写文件、执行命令等。就像机器人的"手"和"眼睛" |
| Hook | - | 钩子，在特定时机自动触发的回调函数。就像设置的"自动报警器"，特定事件发生时自动执行 |
| MCP | Model Context Protocol | 模型上下文协议，让Agent连接外部工具的标准协议 。就像USB接口标准，让各种设备能统一接入 |
| Stream/Streaming | - | 流式传输，数据像流水一样一点点传过来，而不是等全部完成才一次性传输。就像看视频边加载边播放 |
| Async/Await | - | 异步编程语法，让程序不用傻等，可以同时处理多件事。就像你等外卖时还能看手机，不用傻站着 |
| Iterator | - | 迭代器，一种可以逐个获取数据的对象。就像自动发牌机，每次给你一张牌 |
| Context | - | 上下文，AI理解对话的背景信息。就像聊天记录，AI通过它知道你之前说了什么 |
| Token | - | 计费单位，AI处理文字的最小单元。约等于0.75个英文单词或1-2个汉字 |
| Subagent | - | 子代理，由主Agent创建的子任务执行者。就像主管派出去干活的员工 |
第一部分：Claude Agent SDK 简介
1.1 什么是 Claude Agent SDK
┌─────────────────────────────────────────────────┐
│ 你的应用程序 │
│ ┌──────────────────────────────────────────┐ │
│ │ Claude Agent SDK │ │
│ │ ┌────────────────────────────────────┐ │ │
│ │ │ Claude Code核心引擎 │ │ │
│ │ │ - 文件读写能力 │ │ │
│ │ │ - Bash命令执行 │ │ │
│ │ │ - 代码分析与生成 │ │ │
│ │ │ - 网络搜索 │ │ │
│ │ │ - MCP工具调用 │ │ │
│ │ └────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘1.2 SDK vs CLI：什么时候用哪个？
Claude代理核心能力
│
┌───────────────┴───────────────┐
│ │
Claude Code CLI Claude Agent SDK
（命令行工具） （编程接口）
│ │
┌─────┴─────┐ ┌───────┴───────┐
│ │ │ │
人工交互 Shell脚本 Python程序 TypeScript程序| 特性 | Claude Code CLI | Claude Agent SDK |
|---|---|---|
| 使用方式 | 在终端里输入命令 | 在代码里调用函数 |
| 适合场景 | 日常开发、快速任务 | 自动化、批处理、集成到系统 |
| 交互方式 | 人工对话 | 程序控制 |
| 并发能力 | 单会话 | 多代理并行 |
| 定制程度 | 配置文件 | 完全可编程 |
| 学习曲线 | 低（会打字就行） | 中（需要编程基础） |
1.
2.
3.
4.
5.
1.
2.
3.
4.
1.3 支持的编程语言
老金建议：两种SDK功能完全相同，选你最熟悉的语言就好。本教程会同时展示两种语言的代码示例。
1.4 版本演进说明
| 版本阶段 | 包名 | 状态 |
|---|---|---|
| 早期 | @anthropic-ai/claude-code / claude-code-sdk | 已弃用 |
| 当前 | @anthropic-ai/claude-agent-sdk / claude-agent-sdk | 推荐使用 |
第二部分：5分钟快速开始
2.1 环境准备
| 要求项 | 最低版本 | 推荐版本 |
|---|---|---|
| Node.js（TypeScript用） | 18.0.0 | 20.x LTS |
| Python（Python用） | 3.10 | 3.11+ |
| 操作系统 | Windows 10/macOS 12/Ubuntu 20.04 | 最新稳定版 |
2.2 安装SDK
重要提示：Python SDK会自动捆绑Claude Code CLI，无需单独安装！
2.3 配置API密钥
.env文件：ANTHROPIC_API_KEY=sk-ant-api03-...2.4 Hello World Agent
hello_agent.py：启动Agent...
我是Claude，一个AI助手，能帮你编写代码、分析文件、执行命令和解答各种技术问题。
Agent任务完成！src/hello-agent.ts：2.5 验证安装成功
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
ModuleNotFoundError: No module named 'claude_agent_sdk' | SDK没装好 | 重新运行 pip install claude-agent-sdk |
Cannot find module '@anthropic-ai/claude-agent-sdk' | npm包没装好 | 重新运行 npm install |
Authentication failed | API Key没配置 | 检查环境变量是否设置正确 |
Connection timeout | 网络问题 | 检查网络连接，国内可能需要代理 |
第三部分：核心概念深度解析
3.1 query函数：SDK的核心入口
query函数是Agent SDK的心脏，理解它就理解了SDK的一半。| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 是 | 发送给Agent的提示词/任务描述 |
options | Options对象 | 否 | Agent的配置选项 |
query返回一个异步迭代器，产生多种类型的消息：3.2 Agent Loop：代理的工作循环
┌──────────────────────────────────────────────────────┐
│ Agent Loop │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 接收任务 │ → │ 思考 │ → │ 决定行动 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ 需要使用工具？ │ │
│ └───────────────┘ │
│ │ │ │
│ 是 │ │ 否 │
│ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ │ ┌─────────┐ │
│ │ 检查结果 │ ← │ 执行工具 │←──┘ │ 直接回复 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ │
│ ▼ │ │
│ ┌───────────┐ │ │
│ │ 任务完成？ │ │ │
│ └───────────┘ │ │
│ │ │ │ │
│ 否 │ │ 是 │ │
│ │ ▼ ▼ │
│ │ ┌─────────┐ ┌─────────┐ │
│ │ │ 返回结果 │ │ 返回结果 │ │
│ │ └─────────┘ └─────────┘ │
│ │ │
│ └──────────────→ 继续循环 ──────────────────────→│
│ │
└──────────────────────────────────────────────────────┘轮次1：
- Agent思考：需要创建文件
- 使用工具：Write写入calculator.py
- 结果：文件创建成功
- 判断：任务未完成，需要测试
轮次2：
- Agent思考：需要验证代码是否正确
- 使用工具：Bash执行python calculator.py
- 结果：运行成功
- 判断：任务完成
轮次3：
- Agent回复：已成功创建计算器，代码如下...3.3 Tools：Agent的能力来源
| 工具名 | 功能 | 使用场景 |
|---|---|---|
| Read | 读取文件内容 | 分析代码、读取配置 |
| Write | 写入文件内容 | 创建新文件 |
| Edit | 编辑文件 | 修改现有代码 |
| Bash | 执行命令 | 运行脚本、安装依赖 |
| Glob | 文件模式匹配 | 查找特定类型的文件 |
| Grep | 搜索文件内容 | 在代码中查找关键词 |
| Task | 创建子代理 | 并行处理复杂任务 |
| WebSearch | 网络搜索 | 查找最新信息 |
3.4 Subagents：子代理并行处理
传统方式（一个人干所有活）：
┌────────────────────────────────────────────┐
│ 单个Agent顺序处理 │
│ │
│ 处理api/* → 处理models/* → 处理views/* │
│ 2小时 2小时 2小时 │
│ │
│ 总耗时：6小时 │
└────────────────────────────────────────────┘
Subagents方式（主管+多员工）：
┌────────────────────────────────────────────┐
│ 主Agent分配任务，子Agent并行执行 │
│ │
│ 子Agent1: api/* ──┐ │
│ 子Agent2: models/* ──┼──→ 汇总结果 │
│ 子Agent3: views/* ──┘ │
│ 各2小时（同时进行） │
│ │
│ 总耗时：约2.5小时 │
└────────────────────────────────────────────┘| 优势 | 说明 |
|---|---|
| 独立上下文 | 每个子代理有独立的200K上下文窗口 |
| 并行执行 | 最多10个子代理同时运行 |
| 专业化分工 | 每个子代理可以有独立的系统提示词 |
| 失败隔离 | 单个子代理失败不影响其他子代理 |
版本校准（2026-04）：官方 Agent SDK 文档当前要求在 allowed_tools/allowedTools中包含Agent，因为子代理通过 Agent tool 调用。旧资料里可能会看到Task，官方文档说明该工具名在 Claude Code v2.1.63 从Task改为Agent；为兼容旧 SDK，观测tool_use事件时可以同时识别Task和Agent，但新教程示例应写Agent。
3.5 Agent 工具与子代理编排
agents 参数定义子代理，再把 Agent 加入主 Agent 的 allowed_tools。在 Claude Code CLI 交互模式中，普通用户通常不直接手写底层工具调用，而是通过 /agents 管理 agent 配置，或在自然语言里明确要求“使用某个 agent”。| 参数 | 说明 |
|---|---|
description | 告诉 Claude 什么时候应该使用这个子代理 |
prompt | 子代理自己的系统提示词 / 行为规范 |
tools | 子代理可用工具；省略时继承父级可用工具 |
model | 可用 sonnet / opus / haiku / inherit 或完整模型 ID |
background | 是否作为非阻塞后台任务运行 |
maxTurns | 子代理最大 agentic turn 数 |
skills | 明确注入给该子代理的技能列表 |
| 类型 | 用途 | 可用工具 |
|---|---|---|
Explore | 快速搜索代码库（Haiku 驱动，速度最快） | Read、Grep、Glob |
Bash | 执行终端命令、git 操作 | Bash |
code-reviewer | 代码审查 | Read、Grep、Glob、Bash |
general-purpose | 通用多步骤任务 | 全部工具 |
Plan | 设计实现方案 | 全部（不含写入） |
任务A: 构建API ──┐
├──→ 任务C: 运行集成测试
任务B: 配置认证 ──┘1.
2.
3.
tools / disallowedTools 精细控制子代理能力💡 提示：子代理不能再创建子代理（只有一层嵌套），最多可同时运行 10 个并行子代理。
第四部分：实战项目
项目1：代码分析Agent（One-shot模式）
code_analyzer.py：项目2：多工具Agent（Multi-tool模式）
multi_tool_agent.py：项目3：流式交互Agent（Streaming + 自定义工具）
interactive_agent.py：第五部分：高级功能
5.1 MCP服务器集成
| 特性 | SDK内置服务器 | 外部服务器 |
|---|---|---|
| 运行方式 | 在你的Python进程内 | 独立子进程 |
| 性能 | 更快（无IPC开销） | 略慢（需要进程通信） |
| 部署 | 简单（单进程） | 需要管理多进程 |
| 调试 | 更容易 | 需要分别调试 |
| 适用场景 | 简单工具 | 复杂工具、现有MCP服务器 |
5.2 Hooks：在关键时刻自动执行
| Hook类型 | 触发时机 | 用途 |
|---|---|---|
| PreToolUse | 工具执行前 | 验证、过滤危险命令 |
| PostToolUse | 工具执行后 | 记录日志、自动测试 |
| Stop | Agent停止时 | 清理、汇总报告 |
| UserPromptSubmit | 用户提交提示时 | 处理和增强用户输入 |
| SessionStart | 会话开始时 | 加载上次会话状态 |
| SessionEnd | 会话结束时 | 保存会话状态 |
| PreCompact | 上下文压缩前 | 保存关键信息 |
5.3 权限控制
| 模式 | 说明 | 适用场景 |
|---|---|---|
default | 每次文件操作都需要确认 | 生产环境、敏感项目 |
acceptEdits | 自动接受文件编辑 | 个人项目、自动化脚本 |
bypassPermissions | 跳过所有权限检查 | 完全受控环境（谨慎使用） |
5.4 沙箱模式
第六部分：故障排查
6.1 常见错误及解决方案
错误1：模块导入失败
错误2：认证失败
错误3：连接超时
错误4：工具权限被拒绝
错误5：CLI未找到
6.2 调试技巧
第七部分：FAQ 常见问题
Q1: Agent SDK和直接调用Claude API有什么区别？
1.
2.
3.
Q2: 哪个模型性价比最高？
| 场景 | 推荐模型 | 理由 |
|---|---|---|
| 日常开发 | claude-sonnet-4-6 | 能力强、速度快、价格适中 |
| 复杂推理 | claude-opus-4-6 | 最强能力，但价格高 |
| 简单任务 | claude-haiku-4-5-20251001 | 最便宜，适合简单查询 |
Q3: 如何控制Token消耗？
1.
2.
3.
4.
Q4: 子代理和主代理怎么通信？
Agent 工具调用与最终结果回传：1.
Agent 工具创建/调用子代理，指定任务2.
3.
Q5: 可以同时运行多少个子代理？
Q6: 如何在生产环境使用？
1.
2.
3.
4.
5.
Q7: SDK支持流式输出吗？
query函数返回的是AsyncIterator，天然支持流式：Q8: 如何处理长时间运行的任务？
1.
AgentDefinition 中设置 background=True2.
3.
Q9: 自定义工具可以访问外部API吗？
Q10: 如何调试Agent的决策过程？
Q11: SDK会自动重试失败的请求吗？
Q12: 如何在Jupyter Notebook中使用？
Q13: 可以保存和恢复会话吗？
Q14: TypeScript和Python SDK功能一样吗？
Q15: 如何处理大文件？
1.
2.
3.
Q16: SDK支持哪些AI模型？
model参数指定：Q17: 如何测试自定义工具？
Q18: 如何处理API速率限制？
1.
2.
3.
Q19: 安全最佳实践有哪些？
1.
2.
3.
4.
5.
6.
Q20: 有官方示例代码吗？
quick_start.py或quick_start.ts开始。本课总结
核心知识点回顾
1.
2.
3.
4.
5.
6.
最佳实践总结
| 场景 | 建议 |
|---|---|
| 模型选择 | 日常用Sonnet，复杂推理用Opus，简单任务用Haiku |
| 权限控制 | 生产环境用最小权限，开发可以放宽 |
| 子代理 | 大任务拆分并行，注意最多10个同时运行 |
| 自定义工具 | 优先用SDK内置MCP服务器，简单高效 |
| 错误处理 | 使用try/catch，添加重试机制 |
下一步学习
1.
2.
3.
最后更新：2026年4月5日
作者：老金
版本历史
| 版本 | 日期 | 修改内容 |
|---|---|---|
| V1.2 | 2026-02-26 | 更新所有模型引用至最新4.6版本：Sonnet 4.6（claude-sonnet-4-6）、Opus 4.6（claude-opus-4-6）、Haiku 4.5（claude-haiku-4-5-20251001） |
| V1.1 | 2025-12-24 | 修正所有模型名称为最新4.5版本（claude-sonnet-4-5-20250929、claude-opus-4-5-20251101、claude-3-5-haiku-20241022） |
| V1.0 | 2025-12-19 | 初版发布 |
修改于 2026-05-23 09:45:03