Claude Agent SDK 完整指南:把AI编程能力装进你的程序里
课程信息
-
作者:老金
-
GitHub:https://github.com/KimYx0207
-
公众号:老金带你玩AI
-
X(Twitter):老金带你玩AI
-
个人博客:https://aiking.dev
-
预计学时:6-8小时
-
难度等级:⭐⭐⭐ 中级进阶
-
更新日期:2026年10月3日
-
适用版本:Claude Code v2.1.270 为 2026-09-14 的历史参考;截至 2026-10-03 的新增行为按正文标注版本与官方文档
-
信息来源:官方概览、GitHub Python SDK、GitHub TypeScript SDK
版本说明:Claude Agent SDK(原名Claude Code SDK)是2025年Anthropic官方发布的开发工具包。本教程基于最新官方文档编写,如有更新请以官方为准。
版本口径:本章标注的 Claude Code 版本指运行时。Python 与 TypeScript Agent SDK 各有独立版本;安装、升级和调用参数要以所装 SDK 的 API 文档为准。
本课学习目标
老金在个人主页 https://aiking.dev/ 也会持续整理这些 AI 工程化经验,因为 SDK 课必须能落到真实系统里。
完成本课学习后,你将能够:
-
理解SDK的核心价值:掌握Agent SDK与Claude Code CLI的关系和定位
-
5分钟快速上手:完成Hello World Agent的创建和运行
-
掌握核心概念:深入理解Tools、Agent Loop、Context Management
-
独立完成3个实战项目:从one-shot到multi-tool再到streaming模式
-
自定义工具开发:创建SDK内置MCP服务器,扩展Agent能力
-
故障排查技能:解决大多数常见问题
学习路径导航(先看这里!)
这是一篇长教程,不用全看!根据你的目标选择路径。
路径A:快速体验(60分钟)
适合人群:急着体验Agent SDK,想快速跑个Demo
只看这些章节:
术语表(5分钟)
第一部分:SDK简介(10分钟)
第二部分:5分钟快速开始(20分钟)
实战项目1:Hello World Agent(25分钟)
60分钟后你能达到:成功运行第一个Agent,理解基本工作流程
路径B:系统学习(6-8小时)
适合人群:想深入掌握Agent SDK,准备在项目中使用
学习顺序:从头到尾所有章节
建议分段学习:
-
第1天(2小时):第一~三部分(概念+安装+核心原理)
-
第2天(2小时):第四部分(3个实战项目)
-
第3天(2小时):第五~六部分(高级功能+故障排查)
-
第4天(1小时):第七部分FAQ + 总复习
路径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是Anthropic官方提供的开发工具包,让你能够在自己的Python或TypeScript程序中使用Claude Code的全部能力。
生活类比:
想象Claude Code是一辆装配完整的汽车,你可以开着它到处跑。而Agent SDK就是这辆车的发动机、变速箱和底盘的组合包,让你能够打造属于自己的定制车型。
┌─────────────────────────────────────────────────┐
│ 你的应用程序 │
│ ┌──────────────────────────────────────────┐ │
│ │ Claude Agent SDK │ │
│ │ ┌────────────────────────────────────┐ │ │
│ │ │ Claude Code核心引擎 │ │ │
│ │ │ - 文件读写能力 │ │ │
│ │ │ - Bash命令执行 │ │ │
│ │ │ - 代码分析与生成 │ │ │
│ │ │ - 网络搜索 │ │ │
│ │ │ - MCP工具调用 │ │ │
│ │ └────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
1.2 SDK vs CLI:什么时候用哪个?
Claude Code有两种使用方式,选择取决于你的场景:
Claude代理核心能力
│
┌───────────────┴───────────────┐
│ │
Claude Code CLI Claude Agent SDK
(命令行工具) (编程接口)
│ │
┌─────┴─────┐ ┌───────┴───────┐
│ │ │ │
人工交互 Shell脚本 Python程序 TypeScript程序
对比表:
特性
Claude Code CLI
Claude Agent SDK
使用方式
在终端里输入命令
在代码里调用函数
适合场景
日常开发、快速任务
自动化、批处理、集成到系统
交互方式
人工对话
程序控制
并发能力
单会话
多代理并行
定制程度
配置文件
完全可编程
学习曲线
低(会打字就行)
中(需要编程基础)
什么时候用SDK?
-
自动化脚本:每天自动审查代码、生成报告
-
批量处理:一次处理100个文件的重构
-
系统集成:把Claude嵌入你的CI/CD流程
-
多Agent协作:让多个Agent并行工作
-
定制化工具:构建特定领域的AI助手
什么时候用CLI?
-
日常开发:写代码、改bug、问问题
-
快速任务:临时需要AI帮忙的小事
-
学习探索:熟悉Claude的能力
-
不想写代码:就想简单聊聊
1.3 支持的编程语言
Agent SDK目前官方支持两种语言,选择你熟悉的即可:
Python SDK
# 安装命令
pip install claude-agent-sdk
# 特点
- Python 3.10+ 支持
- 异步迭代器(async for)
- 类型提示完善
- 适合:数据科学、AI/ML工作流、自动化脚本
TypeScript/JavaScript SDK
# 安装命令
npm install @anthropic-ai/claude-agent-sdk
# 特点
- Node.js 18+ 支持
- 原生异步生成器
- 完整类型定义
- 适合:Web应用、Node.js服务端、全栈开发
建议:选你最熟悉的语言就好。本教程会同时展示两种语言的代码示例。两种 SDK 的核心工作流相近,但接口和部分功能支持不同;例如 SessionStart、SessionEnd hook 当前支持 TypeScript,Python SDK 尚不支持,复制参数时要查对应语言的参考。
1.4 版本演进说明
Claude Agent SDK经历了从"Claude Code SDK"到"Agent SDK"的品牌升级:
版本阶段
包名
状态
早期
@anthropic-ai/claude-code / claude-code-sdk
已弃用
当前
@anthropic-ai/claude-agent-sdk / claude-agent-sdk
推荐使用
如果你之前用旧版SDK,需要更新导入语句:
# Python旧版(已弃用)
from claude_code_sdk import query, ClaudeCodeOptions
# Python新版(推荐)
from claude_agent_sdk import query, ClaudeAgentOptions
// TypeScript旧版(已弃用)
import { query } from '@anthropic-ai/claude-code';
// TypeScript新版(推荐)
import { query } from '@anthropic-ai/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
最新稳定版
快速检查命令:
# 检查Node.js版本
node --version
# 应显示 v18.0.0 或更高
# 检查Python版本
python --version
# 应显示 Python 3.10 或更高
# 检查npm版本
npm --version
# 应显示 8.0.0 或更高
2.2 安装SDK
Python安装(推荐方式):
# 步骤1:创建虚拟环境(推荐)
python -m venv venv
# 步骤2:激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
# 步骤3:安装Agent SDK
pip install claude-agent-sdk
重要提示:Python SDK会自动捆绑Claude Code CLI,无需单独安装!
TypeScript安装:
# 步骤1:创建项目目录
mkdir my-agent-project
cd my-agent-project
# 步骤2:初始化项目
npm init -y
# 步骤3:安装Agent SDK
npm install @anthropic-ai/claude-agent-sdk
# 步骤4:安装TypeScript开发依赖
npm install -D typescript @types/node ts-node
2.3 配置API密钥
本章以 Claude Console API key 演示认证;SDK 也支持按官方说明配置 Bedrock、Google Cloud Agent Platform、Foundry 等供应商认证。先选认证路径,再运行示例。
方式一:环境变量(推荐)
# Linux/macOS
export ANTHROPIC_API_KEY="sk-ant-api03-..."
# Windows PowerShell
$env:ANTHROPIC_API_KEY="sk-ant-api03-..."
# Windows CMD
set ANTHROPIC_API_KEY=sk-ant-api03-...
方式二:.env文件
创建.env文件:
ANTHROPIC_API_KEY=sk-ant-api03-...
先在选用的环境中安装加载器:Python 使用 pip install python-dotenv,TypeScript 使用 npm install dotenv。创建的 .env 不要提交到仓库,再在代码中加载:
# Python
from dotenv import load_dotenv
load_dotenv()
// TypeScript
import 'dotenv/config';
2.4 Hello World Agent
现在让我们创建第一个Agent!
Python版本 - 创建hello_agent.py:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
async def main():
print('启动Agent...')
# 配置选项
options = ClaudeAgentOptions(
model='claude-sonnet-5' # Sonnet 5(推荐模型)
)
# 执行查询,返回流式响应
async for message in query(
prompt='你好!请用一句话介绍你能做什么?',
options=options
):
# 处理助手回复
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(block.text, end='', flush=True)
print('\n\nAgent任务完成!')
if __name__ == '__main__':
asyncio.run(main())
运行:
python hello_agent.py
预期输出:
启动Agent...
我是Claude,一个AI助手,能帮你编写代码、分析文件、执行命令和解答各种技术问题。
Agent任务完成!
TypeScript版本 - 创建src/hello-agent.ts:
import { query, type Query } from '@anthropic-ai/claude-agent-sdk';
async function main() {
console.log('启动Agent...');
// 创建查询
const stream: Query = query({
prompt: '你好!请用一句话介绍你能做什么?',
options: {
model: 'claude-sonnet-5' // Sonnet 5(推荐)
}
});
// 处理流式响应
for await (const message of stream) {
if (message.type === 'assistant') {
for (const block of message.message.content) {
if (block.type === 'text') {
process.stdout.write(block.text);
}
}
}
}
console.log('\n\nAgent任务完成!');
}
main().catch(console.error);
运行:
npx ts-node src/hello-agent.ts
2.5 验证安装成功
如果看到了 Agent 的回复,说明安装成功。
常见问题快速排查:
错误信息
原因
解决方案
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的一半。
函数签名:
# Python
async def query(
*,
prompt: str | AsyncIterable[dict[str, Any]],
options: ClaudeAgentOptions | None = None,
) -> AsyncIterator[Message]: ...
// TypeScript
function query(params: {
prompt: string | AsyncIterable<SDKUserMessage>;
options?: Options;
}): Query;
核心参数说明:
参数
类型
必填
说明
prompt
string
是
发送给Agent的提示词/任务描述
options
Options对象
否
Agent的配置选项
Options配置项详解:
# Python完整配置示例
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
# 模型选择
model='claude-sonnet-5', # Sonnet 5(推荐),也可选Opus 4.8或Haiku 4.5
# 系统提示词(定义Agent的角色和行为)
system_prompt='你是一个Python专家,专注于代码质量和最佳实践。',
# 工作目录(Agent操作文件的根目录)
cwd='/path/to/your/project',
# 最大对话轮次(防止无限循环)
max_turns=10,
# 权限模式
permission_mode='default', # 可选:default, acceptEdits, bypassPermissions
# 允许使用的工具
allowed_tools=['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'],
# MCP服务器配置(扩展工具)
mcp_servers={
'my_server': {
'command': 'python',
'args': ['-m', 'my_mcp_server']
}
}
)
返回值:流式消息
query返回一个异步迭代器,产生多种类型的消息:
# 直接使用 SDK 导出的类型;ToolUseBlock / ToolResultBlock 属于内容块,
# 不是 query 单独产出的顶层消息。
from claude_agent_sdk import (
Message, AssistantMessage, UserMessage, SystemMessage,
ResultMessage, TextBlock, ToolUseBlock, ToolResultBlock,
)
# 具体 SDK 版本还可能产生流事件、限流事件等消息,按官方参考处理。
处理消息的标准模式:
async for message in query(prompt="你的任务", options=options):
if isinstance(message, AssistantMessage):
# 处理AI回复
for block in message.content:
if isinstance(block, TextBlock):
print(block.text)
elif isinstance(block, ToolUseBlock):
print(f"调用工具: {block.name}")
elif isinstance(message, ResultMessage):
# 任务完成
print(f"最终结果: {message.result}")
3.2 Agent Loop:代理的工作循环
Agent不是简单地"问一句答一句",而是有一个完整的工作循环。
Agent Loop工作流程:
┌──────────────────────────────────────────────────────┐
│ Agent Loop │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 接收任务 │ → │ 思考 │ → │ 决定行动 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ 需要使用工具? │ │
│ └───────────────┘ │
│ │ │ │
│ 是 │ │ 否 │
│ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ │ ┌─────────┐ │
│ │ 检查结果 │ ← │ 执行工具 │←──┘ │ 直接回复 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ │
│ ▼ │ │
│ ┌───────────┐ │ │
│ │ 任务完成? │ │ │
│ └───────────┘ │ │
│ │ │ │ │
│ 否 │ │ 是 │ │
│ │ ▼ ▼ │
│ │ ┌─────────┐ ┌─────────┐ │
│ │ │ 返回结果 │ │ 返回结果 │ │
│ │ └─────────┘ └─────────┘ │
│ │ │
│ └──────────────→ 继续循环 ──────────────────────→│
│ │
└──────────────────────────────────────────────────────┘
实际例子:让Agent"创建一个Python计算器"
轮次1:
- Agent思考:需要创建文件
- 使用工具:Write写入calculator.py
- 结果:文件创建成功
- 判断:任务未完成,需要测试
轮次2:
- Agent思考:需要验证代码是否正确
- 使用工具:Bash执行python calculator.py
- 结果:运行成功
- 判断:任务完成
轮次3:
- Agent回复:已成功创建计算器,代码如下...
控制Agent Loop的参数:
options = ClaudeAgentOptions(
max_turns=10, # 最多10轮,防止无限循环
# 如果任务简单,可以设小一点节省token
)
3.3 Tools:Agent的能力来源
Tools(工具)是Agent能够"做事"的关键。没有工具,Agent只能"说话"不能"干活"。
内置工具清单:
工具名
功能
使用场景
Read
读取文件内容
分析代码、读取配置
Write
写入文件内容
创建新文件
Edit
编辑文件
修改现有代码
Bash
执行命令
运行脚本、安装依赖
Glob
文件模式匹配
查找特定类型的文件
Grep
搜索文件内容
在代码中查找关键词
Agent
创建子代理
并行处理复杂任务
WebSearch
网络搜索
查找最新信息
限制工具权限:
# 这个例子只提供三个内置文件查询工具,没有额外的 MCP 服务器。
options = ClaudeAgentOptions(
tools=['Read', 'Glob', 'Grep'],
allowed_tools=['Read', 'Glob', 'Grep'],
)
# 沿用默认工具与审批规则;不等于所有调用都自动允许。
options = ClaudeAgentOptions()
# tools 决定可用的内置工具,allowed_tools 决定哪些调用可免审批。
# 配了 MCP、hooks 或其他扩展时,还须单独审核它们的能力。
自定义工具(SDK MCP Server):
这是Agent SDK的强大功能之一!你可以创建自己的工具:
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient
import ast
import math
import operator
def safe_calculate(expression: str):
"""教学计算器:只接受有限长度的基本运算,不执行 Python 代码。"""
if not isinstance(expression, str) or not expression.strip() or len(expression) > 200:
raise ValueError("请输入不超过 200 字符的数学表达式")
tree = ast.parse(expression, mode="eval")
if sum(1 for _ in ast.walk(tree)) > 100:
raise ValueError("表达式过于复杂")
binary = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul,
ast.Div: operator.truediv, ast.Mod: operator.mod}
unary = {ast.UAdd: operator.pos, ast.USub: operator.neg}
def evaluate(node):
if isinstance(node, ast.Constant) and type(node.value) in (int, float):
value = node.value
elif isinstance(node, ast.BinOp) and type(node.op) in binary:
value = binary[type(node.op)](evaluate(node.left), evaluate(node.right))
elif isinstance(node, ast.UnaryOp) and type(node.op) in unary:
value = unary[type(node.op)](evaluate(node.operand))
else:
raise ValueError("只支持数字、括号和 + - * / % 运算")
if not math.isfinite(value) or abs(value) > 1_000_000_000_000:
raise ValueError("数值或中间结果超出教学示例的范围")
return value
return evaluate(tree.body)
# 使用@tool装饰器定义工具
@tool("greet", "向用户问好", {"name": str})
async def greet_user(args):
name = args.get('name', '朋友')
return {
"content": [
{"type": "text", "text": f"你好,{name}!很高兴认识你!"}
]
}
@tool("calculate", "执行数学计算", {"expression": str})
async def calculate(args):
expression = args.get('expression', '0')
try:
result = safe_calculate(expression)
return {"content": [{"type": "text", "text": f"计算结果:{result}"}]}
except Exception as e:
return {"content": [{"type": "text", "text": f"计算错误:{str(e)}"}]}
# 创建SDK MCP服务器
my_tools = create_sdk_mcp_server(
name="my-tools",
version="1.0.0",
tools=[greet_user, calculate]
)
# 在Agent中使用
options = ClaudeAgentOptions(
mcp_servers={"tools": my_tools},
allowed_tools=["mcp__tools__greet", "mcp__tools__calculate"]
)
3.4 Subagents:子代理并行处理
当任务太复杂或太大时,单个Agent可能会遇到上下文窗口限制。Subagents(子代理)解决了这个问题。
类比理解:
传统方式(一个人干所有活):
┌────────────────────────────────────────────┐
│ 单个Agent顺序处理 │
│ │
│ 处理api/* → 处理models/* → 处理views/* │
│ 2小时 2小时 2小时 │
│ │
│ 总耗时:6小时 │
└────────────────────────────────────────────┘
Subagents方式(主管+多员工):
┌────────────────────────────────────────────┐
│ 主Agent分配任务,子Agent并行执行 │
│ │
│ 子Agent1: api/* ──┐ │
│ 子Agent2: models/* ──┼──→ 汇总结果 │
│ 子Agent3: views/* ──┘ │
│ 各2小时(同时进行) │
│ │
│ 总耗时:约2.5小时 │
└────────────────────────────────────────────┘
核心优势:
优势
说明
独立上下文
每个子代理有自己的上下文,容量取决于模型和运行时
并行执行
并发取决于运行时上限、资源和任务配置;不能统一写死为 10
专业化分工
每个子代理可以有独立的系统提示词
失败隔离
单个子代理失败不影响其他子代理
使用Subagents的方式:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
# 当前 SDK 通过 Agent 工具创建子代理
options = ClaudeAgentOptions(
allowed_tools=['Read', 'Grep', 'Glob', 'Edit', 'Write', 'Agent'],
agents={
'api-refactorer': AgentDefinition(
description='负责 API 目录重构,适合处理 src/api 下的模块迁移任务。',
prompt='你是 API 重构专家。只处理分配给你的目录,返回修改摘要和风险点。',
tools=['Read', 'Grep', 'Glob', 'Edit', 'Write'],
model='sonnet',
),
'model-typist': AgentDefinition(
description='负责数据模型和 TypeScript 类型补全。',
prompt='你是 TypeScript 类型建模专家。优先保持兼容性,避免无关重构。',
tools=['Read', 'Grep', 'Glob', 'Edit', 'Write'],
),
},
max_turns=50,
system_prompt="""你是一个项目重构专家。
当遇到大型任务时,优先使用已定义的子代理并行处理。
每个子代理应该专注于一个独立的模块或目录。"""
)
prompt = """请重构以下目录的代码:
1. src/api/ - 将CommonJS改为ES Module
2. src/models/ - 添加TypeScript类型
3. src/views/ - 优化组件结构
请使用子代理并行处理这三个目录。"""
async def main():
async for message in query(prompt=prompt, options=options):
print(message)
if __name__ == "__main__":
asyncio.run(main())
版本校准(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 工具与子代理编排
在 SDK 中,推荐用 agents 参数定义子代理,再把 Agent 加入主 Agent 的 allowed_tools。在 Claude Code CLI 交互模式中,普通用户通常不直接手写底层工具调用,而是通过 /agents 管理 agent 配置,或在自然语言里明确要求“使用某个 agent”。
AgentDefinition 核心字段:
参数
说明
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
设计实现方案
全部(不含写入)
并行编排方式:
主 Agent 可以一次启动多个适合的子代理。子代理各自拥有独立上下文,只把最终结果返回给父级;如果后续步骤依赖前置结论,把依赖关系写进父级 prompt,让父级在收到结果后再继续分配下一步。
任务A: 构建API ──┐
├──→ 任务C: 运行集成测试
任务B: 配置认证 ──┘
子代理上下文注入:
子代理获取上下文的三种方式:
-
Skills 注入:在定义中指定 skills 字段,完整技能内容直接注入子代理
-
Memory 持久化:子代理可拥有持久记忆目录,跨会话积累知识
-
工具访问控制:通过 tools / disallowedTools 精细控制子代理能力
💡 提示:从 Claude Code v2.1.219 起,子代理默认可以继续派出子代理,最多到主会话下方三层;CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 可以限制为一层。并行数量仍受运行时、配置和资源影响,不能统一写成最多 10 个。SDK 中嵌套的后台子代理如果在派出它的子代理结束后才完成,结果会交回主会话,编排时要跟踪最终结果。
第四部分:实战项目
项目1:代码分析Agent(One-shot模式)
目标:创建一个能分析代码文件并给出改进建议的Agent
难度:⭐ 入门
Python实现 - code_analyzer.py:
"""
代码分析Agent - 分析指定文件的代码质量
"""
import asyncio
import sys
from pathlib import Path
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
async def analyze_code(file_path: str) -> None:
"""分析指定文件的代码质量"""
# 检查文件是否存在
path = Path(file_path)
if not path.exists():
print(f"错误:文件 {file_path} 不存在")
return
print(f"分析文件: {path.absolute()}")
print("=" * 50)
# 配置Agent
options = ClaudeAgentOptions(
model='claude-sonnet-5',
cwd=str(Path.cwd()),
tools=['Read', 'Glob', 'Grep'], # 限定这个示例的内置工具集合
allowed_tools=['Read', 'Glob', 'Grep'], # 预批准这些读取工具
max_turns=5,
system_prompt="""你是一位资深代码审查专家。
请分析代码并提供:
1. 代码概述(功能和结构)
2. 潜在问题(bug风险、安全隐患)
3. 改进建议(可读性、性能、最佳实践)
请使用中文回复,格式清晰。"""
)
prompt = f"""请分析以下文件的代码质量:{path.absolute()}
使用Read工具读取文件内容,然后给出详细分析。"""
# 执行分析
async for message in query(prompt=prompt, options=options):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(block.text, end='', flush=True)
print("\n" + "=" * 50)
print("分析完成!")
def main():
# 从命令行参数获取文件路径
if len(sys.argv) < 2:
print("用法: python code_analyzer.py <文件路径>")
print("示例: python code_analyzer.py ./my_code.py")
return
file_path = sys.argv[1]
asyncio.run(analyze_code(file_path))
if __name__ == '__main__':
main()
使用方法:
# 分析Python文件
python code_analyzer.py ./my_script.py
# 分析JavaScript文件
python code_analyzer.py ./app.js
项目2:多工具Agent(Multi-tool模式)
目标:创建一个能读写文件、执行命令的全能Agent
难度:⭐⭐ 进阶
Python实现 - multi_tool_agent.py:
"""
多工具Agent - 可以读写文件、执行命令的全能助手
"""
import asyncio
from pathlib import Path
from claude_agent_sdk import (
query,
ClaudeAgentOptions,
AssistantMessage,
UserMessage,
TextBlock,
ToolUseBlock,
ToolResultBlock
)
async def run_multi_tool_agent(task: str) -> None:
"""运行多工具Agent执行任务"""
print(f"任务: {task}")
print("=" * 60)
options = ClaudeAgentOptions(
model='claude-sonnet-5', # Sonnet 5
cwd=str(Path.cwd()),
allowed_tools=['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'],
max_turns=15,
permission_mode='acceptEdits', # 自动接受文件编辑
system_prompt="""你是一个全能开发助手,可以:
- 读取和分析文件
- 创建和修改文件
- 执行命令行命令
- 搜索文件内容
执行任务时:
1. 先分析需要做什么
2. 分步骤执行
3. 每步都验证结果
4. 最后总结完成情况
使用中文回复。"""
)
# 执行任务
async for message in query(prompt=task, options=options):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(block.text, end='', flush=True)
elif isinstance(block, ToolUseBlock):
print(f"\n[使用工具: {block.name}]")
elif isinstance(message, UserMessage):
for block in message.content:
if isinstance(block, ToolResultBlock):
print(f"[工具结果: {block.tool_use_id}; 错误: {bool(block.is_error)}]")
print("\n" + "=" * 60)
print("任务执行完成!")
async def main():
# 示例任务列表
tasks = [
"创建一个名为hello.py的文件,内容是打印'Hello, Agent SDK!',然后运行它",
"查找当前目录下所有的.py文件,列出它们的名称",
"创建一个简单的README.md文件,描述这是一个Agent SDK演示项目",
]
print("可用任务:")
for i, task in enumerate(tasks, 1):
print(f" {i}. {task}")
print()
# 选择任务
choice = input("输入任务编号(1-3)或自定义任务: ").strip()
if choice in ['1', '2', '3']:
task = tasks[int(choice) - 1]
else:
task = choice
await run_multi_tool_agent(task)
if __name__ == '__main__':
asyncio.run(main())
运行示例:
python multi_tool_agent.py
# 输出:
# 可用任务:
# 1. 创建一个名为hello.py的文件...
# 2. 查找当前目录下所有的.py文件...
# 3. 创建一个简单的README.md文件...
#
# 输入任务编号(1-3)或自定义任务: 1
项目3:流式交互Agent(Streaming + 自定义工具)
目标:创建一个带有自定义工具的交互式Agent
难度:⭐⭐⭐ 高级
Python实现 - interactive_agent.py:
"""
交互式Agent - 带有自定义工具的流式对话Agent
"""
import asyncio
from datetime import datetime
from claude_agent_sdk import (
tool,
create_sdk_mcp_server,
ClaudeAgentOptions,
ClaudeSDKClient,
AssistantMessage,
TextBlock,
ToolUseBlock
)
import ast
import math
import operator
def safe_calculate(expression: str):
"""教学计算器:只接受有限长度的基本运算,不执行 Python 代码。"""
if not isinstance(expression, str) or not expression.strip() or len(expression) > 200:
raise ValueError("请输入不超过 200 字符的数学表达式")
tree = ast.parse(expression, mode="eval")
if sum(1 for _ in ast.walk(tree)) > 100:
raise ValueError("表达式过于复杂")
binary = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul,
ast.Div: operator.truediv, ast.Mod: operator.mod}
unary = {ast.UAdd: operator.pos, ast.USub: operator.neg}
def evaluate(node):
if isinstance(node, ast.Constant) and type(node.value) in (int, float):
value = node.value
elif isinstance(node, ast.BinOp) and type(node.op) in binary:
value = binary[type(node.op)](evaluate(node.left), evaluate(node.right))
elif isinstance(node, ast.UnaryOp) and type(node.op) in unary:
value = unary[type(node.op)](evaluate(node.operand))
else:
raise ValueError("只支持数字、括号和 + - * / % 运算")
if not math.isfinite(value) or abs(value) > 1_000_000_000_000:
raise ValueError("数值或中间结果超出教学示例的范围")
return value
return evaluate(tree.body)
# ============ 自定义工具定义 ============
@tool("get_time", "获取当前时间", {})
async def get_current_time(args):
"""返回当前时间"""
now = datetime.now()
return {
"content": [{
"type": "text",
"text": f"当前时间:{now.strftime('%Y-%m-%d %H:%M:%S')}"
}]
}
@tool("calculate", "执行数学计算", {
"expression": str
})
async def calculate(args):
"""执行数学计算"""
expression = args.get('expression', '0')
try:
result = safe_calculate(expression)
return {"content": [{"type": "text", "text": f"{expression} = {result}"}]}
except Exception as e:
return {"content": [{"type": "text", "text": f"计算错误:{str(e)}"}]}
@tool("todo_add", "添加待办事项", {
"item": str
})
async def add_todo(args):
"""添加待办事项"""
item = args.get('item', '')
if not item:
return {"content": [{"type": "text", "text": "错误:待办事项不能为空"}]}
# 这里可以连接数据库,简化起见用文件存储
with open('todos.txt', 'a', encoding='utf-8') as f:
f.write(f"[ ] {item}\n")
return {"content": [{"type": "text", "text": f"已添加待办事项:{item}"}]}
@tool("todo_list", "列出所有待办事项", {})
async def list_todos(args):
"""列出待办事项"""
try:
with open('todos.txt', 'r', encoding='utf-8') as f:
todos = f.read().strip()
if not todos:
return {"content": [{"type": "text", "text": "待办事项列表为空"}]}
return {"content": [{"type": "text", "text": f"待办事项列表:\n{todos}"}]}
except FileNotFoundError:
return {"content": [{"type": "text", "text": "待办事项列表为空"}]}
# ============ Agent配置 ============
# 创建自定义工具服务器
custom_tools = create_sdk_mcp_server(
name="custom-tools",
version="1.0.0",
tools=[get_current_time, calculate, add_todo, list_todos]
)
# Agent配置
def get_options():
return ClaudeAgentOptions(
model='claude-sonnet-5', # Sonnet 5(推荐)
mcp_servers={"custom": custom_tools},
allowed_tools=[
"Read", "Write", "Bash",
"mcp__custom__get_time",
"mcp__custom__calculate",
"mcp__custom__todo_add",
"mcp__custom__todo_list"
],
permission_mode='acceptEdits',
system_prompt="""你是一个智能助手,可以使用以下工具:
1. **get_time**: 获取当前时间
2. **calculate**: 执行数学计算
3. **todo_add**: 添加待办事项
4. **todo_list**: 列出所有待办事项
5. **Read/Write/Bash**: 文件操作和命令执行
请根据用户需求选择合适的工具。使用中文回复。
当用户说"退出"或"再见"时,友好地告别。"""
)
# ============ 交互循环 ============
async def interactive_chat():
"""交互式对话循环"""
print("=" * 60)
print("欢迎使用交互式Agent!")
print("你可以:")
print(" - 问我现在几点了")
print(" - 让我计算数学题(如:计算 123 * 456)")
print(" - 添加待办事项(如:添加待办 写周报)")
print(" - 查看待办事项列表")
print(" - 让我读写文件或执行命令")
print("输入 '退出' 或 '再见' 结束对话")
print("=" * 60)
print()
async with ClaudeSDKClient(options=get_options()) as client:
while True:
# 获取用户输入
try:
user_input = input("你: ").strip()
except EOFError:
break
if not user_input:
continue
# 检查退出
if user_input.lower() in ['退出', '再见', 'exit', 'quit', 'bye']:
print("\nAgent: 再见!祝你有愉快的一天!")
break
# 发送消息
await client.query(user_input)
# 处理响应
print("Agent: ", end='', flush=True)
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(block.text, end='', flush=True)
elif isinstance(block, ToolUseBlock):
print(f"\n[调用工具: {block.name}]", end='', flush=True)
print() # 换行
async def main():
await interactive_chat()
if __name__ == '__main__':
asyncio.run(main())
运行示例:
python interactive_agent.py
# 交互示例:
# ============================================================
# 欢迎使用交互式Agent!
# ...
# ============================================================
#
# 你: 现在几点了?
# Agent: [调用工具: get_time]
# 当前时间是 2025-12-19 15:30:45
#
# 你: 计算 123 * 456
# Agent: [调用工具: calculate]
# 123 * 456 = 56088
#
# 你: 添加待办 写Agent SDK教程
# Agent: [调用工具: todo_add]
# 已添加待办事项:写Agent SDK教程
#
# 你: 退出
# Agent: 再见!祝你有愉快的一天!
第五部分:高级功能
5.1 MCP服务器集成
MCP(Model Context Protocol)让你可以连接外部工具和服务。
外部MCP服务器配置:
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(
mcp_servers={
# 文件系统服务器
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
},
# 历史 SQLite reference server:已归档,仅作教学参考,需先安装 uv。
# 新项目先挑选有维护的实现并核查它的工具名、权限和启动参数。
"database": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "./data/app.db"]
},
# 自定义Python服务器
"custom": {
"command": "python",
"args": ["-m", "my_mcp_server"],
"env": {
"API_KEY": "your-api-key"
}
}
},
allowed_tools=[
"mcp__filesystem__read_text_file",
"mcp__database__read_query",
"mcp__custom__my_tool"
]
)
SDK内置MCP服务器 vs 外部服务器:
特性
SDK内置服务器
外部服务器
运行方式
在你的Python进程内
独立子进程
性能
更快(无IPC开销)
略慢(需要进程通信)
部署
简单(单进程)
需要管理多进程
调试
更容易
需要分别调试
适用场景
简单工具
复杂工具、现有MCP服务器
5.2 Hooks:在关键时刻自动执行
Hooks(钩子)让你可以在Agent执行的特定时机插入自定义逻辑。
可用的Hook类型:
Hook类型
触发时机
用途
PreToolUse
工具执行前
验证、过滤危险命令
PostToolUse
工具执行后
记录日志、自动测试
Stop
Agent停止时
清理、汇总报告
UserPromptSubmit
用户提交提示时
处理和增强用户输入
SessionStart(TypeScript)
会话开始时
初始化日志和状态;Python SDK 当前不支持
SessionEnd(TypeScript)
会话结束时
清理资源和保存应用状态;Python SDK 当前不支持
PreCompact
上下文压缩前
保存关键信息
Python Hooks示例:
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher
# 定义Hook函数
async def block_dangerous_commands(input_data, tool_use_id, context):
"""阻止危险的Bash命令"""
tool_name = input_data.get("tool_name")
tool_input = input_data.get("tool_input", {})
# 只检查Bash命令
if tool_name != "Bash":
return {}
command = tool_input.get("command", "")
# 危险命令黑名单
dangerous_patterns = ["rm -rf", "sudo rm", ":(){ :|:& };:", "dd if="]
for pattern in dangerous_patterns:
if pattern in command:
return {
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": f"危险命令被阻止:包含 '{pattern}'"
}
}
return {} # Hook 不作决定,继续走正常权限流程
# 这里仅演示几个字面子串的匹配:rm -r -f 等写法不会命中。
# 它不是完整的 shell 命令审计,实际部署还需权限规则和沙箱。
async def log_tool_results(input_data, tool_use_id, context):
"""记录工具执行结果"""
tool_name = input_data.get("tool_name")
print(f"[日志] 工具 {tool_name} 执行完成")
return {}
# 配置Hooks
options = ClaudeAgentOptions(
allowed_tools=["Bash", "Read", "Write"],
hooks={
"PreToolUse": [
HookMatcher(matcher="Bash", hooks=[block_dangerous_commands]),
],
"PostToolUse": [
HookMatcher(matcher=".*", hooks=[log_tool_results]),
],
}
)
5.3 权限控制
Agent SDK提供多种权限控制方式,需要按任务明确选择。不要只根据交互终端的默认模式推断SDK:会拉取功能开关的SDK会话通常从 Manual 开始;第三方提供商或关闭遥测等不拉取功能开关的会话,从 v2.1.285 起通常从 auto 开始,组织策略可能改变结果。希望本章练习遵守正常权限规则时,显式设 permission_mode="default",并用权限回调处理需要确认的操作。具体条件见官方启动权限模式。
权限模式:
模式
说明
适用场景
default
沿用正常权限规则;只读等部分调用无需审批,其余按规则或回调决定
需要人工或程序处理审批的场景
acceptEdits
自动接受文件编辑
个人项目、自动化脚本
bypassPermissions
跳过所有权限检查
完全受控环境(谨慎使用)
工具白名单:
# 文件查询 Agent:这个例子未配置 MCP 或 hooks。
readonly_options = ClaudeAgentOptions(
tools=['Read', 'Glob', 'Grep'],
allowed_tools=['Read', 'Glob', 'Grep'],
)
# 代码审查:仅预批准这些测试入口,不给整个 Bash 工具免审批。
# 测试脚本本身仍可能写文件;提示词不是系统隔离边界。
review_options = ClaudeAgentOptions(
tools=['Read', 'Glob', 'Grep', 'Bash'],
allowed_tools=['Read', 'Glob', 'Grep', 'Bash(pytest *)', 'Bash(npm test)'],
permission_mode='dontAsk',
system_prompt="审查代码并运行已批准的测试,汇报结果。",
)
# 自动接受文件编辑;其他命令仍按权限规则处理。
edit_options = ClaudeAgentOptions(
tools=['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep', 'Agent'],
permission_mode='acceptEdits',
)
5.4 沙箱模式
下面用 sandbox.enabled 启用 Bash 沙箱,并设置 allowUnsandboxedCommands=False,让模型不能通过 dangerouslyDisableSandbox 请求脱离沙箱。can_use_tool 只处理正常权限流程最终要求审批的调用,已经被规则或权限模式批准的调用不会进入它;若要检查每一次工具调用,应使用 PreToolUse hook。沙箱支持的平台、文件和网络范围仍须按官方沙箱文档配置。
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import ToolPermissionContext, PermissionResultAllow, PermissionResultDeny
# 自定义沙箱控制
async def can_use_tool(
tool_name: str, tool_input: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
"""自定义工具权限检查"""
# 检查是否请求禁用沙箱
if tool_name == "Bash" and tool_input.get("dangerouslyDisableSandbox"):
print(f"警告:请求在沙箱外执行命令:{tool_input.get('command')}")
# 返回Deny拒绝,Allow允许
return PermissionResultDeny(message="禁止在沙箱外执行命令")
return PermissionResultAllow()
options = ClaudeAgentOptions(
sandbox={
"enabled": True, # 启用沙箱
"allowUnsandboxedCommands": False # 禁止请求沙箱外执行
},
permission_mode="default",
can_use_tool=can_use_tool # 自定义权限检查
)
第六部分:故障排查
6.1 常见错误及解决方案
错误1:模块导入失败
# 示意错误信息;实际文案以运行时为准
ModuleNotFoundError: No module named 'claude_agent_sdk'
原因:SDK未安装或虚拟环境未激活
解决方案:
# 确认虚拟环境已激活
source venv/bin/activate # Linux/macOS
# 或
venv\Scripts\activate # Windows
# 重新安装
pip install claude-agent-sdk
# 验证安装
pip show claude-agent-sdk
错误2:认证失败
# 示意错误信息;实际文案以运行时为准
AuthenticationError: Invalid API key
原因:API Key未配置或无效
解决方案:
# 检查环境变量
echo $ANTHROPIC_API_KEY # Linux/macOS
echo %ANTHROPIC_API_KEY% # Windows
# 重新设置
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"
# 或在代码中设置(不推荐)
import os
os.environ["ANTHROPIC_API_KEY"] = "your-key"
错误3:连接超时
# 示意错误信息;实际文案以运行时为准
ConnectionTimeout: Request timed out
原因:网络问题或API服务繁忙
解决方案:
# 检查网络连接
ping api.anthropic.com
# 国内用户可能需要代理
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
错误4:工具权限被拒绝
# 示意错误信息;实际文案以运行时为准
工具调用需要审批,当前配置未取得许可
原因:工具不在白名单中
解决方案:
# 添加需要的工具到白名单
options = ClaudeAgentOptions(
allowed_tools=['Read', 'Write', 'Edit'] # 添加Write
)
错误5:CLI未找到
# 示意错误信息;实际文案以运行时为准
CLINotFoundError: Claude Code CLI not found
原因:捆绑的CLI未正确安装
解决方案:
# 方法1:重新安装SDK
pip uninstall claude-agent-sdk
pip install claude-agent-sdk
# 方法2:手动安装CLI
curl -fsSL https://claude.ai/install.sh | bash
# 方法3:指定CLI路径
options = ClaudeAgentOptions(
cli_path="/path/to/claude"
)
6.2 调试技巧
启用详细日志:
import logging
# 设置日志级别
logging.basicConfig(level=logging.DEBUG)
# 需要接收 CLI 子进程的标准错误时,可在选项中设置 stderr 回调:
# ClaudeAgentOptions(stderr=lambda line: logging.debug("CLI: %s", line))
打印消息详情:
async for message in query(prompt="...", options=options):
print(f"消息类型: {type(message).__name__}")
print(f"消息内容: {message}")
print("-" * 40)
第七部分:FAQ 常见问题
Q1: Agent SDK和直接调用Claude API有什么区别?
答:主要区别有三点:
-
Agent SDK有Agent Loop:可以自动多轮对话,使用工具完成复杂任务
-
Agent SDK有内置工具:文件操作、命令执行等能力开箱即用
-
Agent SDK支持子代理:可以并行处理大规模任务
如果你只需要简单问答,用Claude API即可。如果需要AI"干活"(操作文件、执行命令),用Agent SDK。
Q2: 哪个模型性价比最高?
答:推荐模型选择:
场景
推荐模型
理由
日常开发
claude-sonnet-5
能力强、速度快、价格适中
复杂推理
当前账号可用的 Opus 型号
适合复杂推理,先比较实际质量与价格
简单任务
claude-haiku-4-5-20251001
本章轻量任务示例,是否可用及价格以供应商为准
# 性价比之选
options = ClaudeAgentOptions(model='claude-sonnet-5')
Q3: 如何控制Token消耗?
答:几个技巧:
-
设置max_turns:限制对话轮数
-
精简system_prompt:不要写太长的系统提示
-
任务明确:给出清晰具体的任务描述
-
使用更小的模型:简单任务用Haiku
options = ClaudeAgentOptions(
model='claude-haiku-4-5-20251001', # 便宜模型
max_turns=5, # 限制轮数
system_prompt="简洁回复。" # 简短提示
)
Q4: 子代理和主代理怎么通信?
答:通过 Agent 工具调用与最终结果回传:
-
主 Agent 通过 Agent 工具创建/调用子代理,指定任务
-
子代理执行任务并返回结果
-
主 Agent 收到子代理最终消息,作为后续汇总或下一步决策的输入
子代理运行在独立上下文里,父级不会自动继承它读过的所有文件和中间工具结果;需要保留的信息应让子代理在最终回复里明确写出来。
Q5: 可以同时运行多少个子代理?
答:没有可以套用到所有版本和环境的“最多10个”结论。并发受 Claude Code 版本、配置、权限、资源和任务类型影响;本课的 SDK 调用示例也没有创建固定大小的代理池。先按少量、职责清晰的子任务验证,再参照官方子代理限制调整。
Q6: 如何在生产环境使用?
答:几个建议:
-
使用权限控制:用 tools 限定内置工具集合;allowed_tools 只预批准具体调用,MCP 与 hooks 另行检查
-
启用沙箱:防止危险命令
-
添加Hooks:记录日志、过滤危险操作
-
设置超时:防止任务卡住
-
监控Token消耗:控制成本
# 文件分析配置示例;未配置 MCP 和 hooks。
# 整体部署还需要结合自己的数据范围、鉴权和隔离要求设计。
production_options = ClaudeAgentOptions(
model='sonnet',
tools=['Read', 'Glob', 'Grep'],
allowed_tools=['Read', 'Glob', 'Grep'],
permission_mode='dontAsk',
max_turns=10,
)
Q7: SDK支持流式输出吗?
答:是的!query函数返回的是AsyncIterator,天然支持流式:
async for message in query(prompt="...", options=options):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(block.text, end='', flush=True) # 流式打印
Q8: 如何处理长时间运行的任务?
答:
-
使用后台运行的子代理:在 AgentDefinition 中设置 background=True,并持续消费 SDK 的消息,直到取得任务的最终结果;后台执行仍依赖宿主进程与会话运行,不会自动变成跨进程的持久任务
-
区分命令超时与后台时限:v2.1.288 的 -p、SDK、CI、cloud等无人值守会话中,后台 Bash/PowerShell 默认30分钟;Claude在 run_in_background 中传入的 timeout 可以指定时限,通常最大2小时。前台命令超时后转后台时,从转移那刻再计时。终端、桌面与VS Code里的交互会话不受这个后台时限约束;v2.1.285–287曾对所有会话应用时限。--bare 不运行后台任务,命令超时后停止。普通 -p 也会在最终结果后不久结束后台命令,不能收到一条结果就把宿主退出,再期待子任务继续完成。长任务要持续消费消息、拿到最终结果并负责停止/清理。完整规则见官方后台命令时限。
-
使用异步并行
prompt = """请使用子代理并行处理:
- 子代理1:分析src目录
- 子代理2:分析tests目录
如果这些子代理被配置为 background=True,请持续跟踪它们的最终结果后再汇总。"""
Q9: 自定义工具可以访问外部API吗?
答:可以!自定义工具可以调用外部 API。下面只展示异步请求的写法,https://api.weather.com/{city} 是接口占位示意,不能当作可用的天气 API 直接运行;实际接入时要替换成服务商提供的端点,并补上认证、超时和响应状态检查。片段还需要本章的 tool 导入及 httpx 依赖:
import httpx
@tool("weather", "获取天气信息", {"city": str})
async def get_weather(args):
city = args.get('city')
async with httpx.AsyncClient() as client:
response = await client.get(f"https://api.weather.com/{city}")
data = response.json()
return {"content": [{"type": "text", "text": f"{city}天气:{data}"}]}
Q10: 如何调试Agent的决策过程?
答:打印所有消息类型。下面片段需先导入 UserMessage;工具结果在它的 content 中,不能把内容块当成顶层消息判断。
async for message in query(prompt="...", options=options):
print(f"[{type(message).__name__}] ", end='')
if isinstance(message, AssistantMessage):
print("AI思考中...")
for block in message.content:
if isinstance(block, TextBlock):
print(f" 文本: {block.text[:100]}...")
elif isinstance(block, ToolUseBlock):
print(f" 调用工具: {block.name}({block.input})")
elif isinstance(message, UserMessage):
for block in message.content:
if isinstance(block, ToolResultBlock):
print(f"工具结果: {str(block.content)[:100]}...")
Q11: SDK会自动重试失败的请求吗?
答:运行时会处理部分请求重试。下面的 tenacity 包装会重新执行整个 query,前一次已经完成的写文件、命令或外部 API 操作可能再次发生,所以只把它用于只读或已经设计成可重复执行的任务;其他任务应先确认执行状态,再决定如何继续。示例需安装 tenacity。
import asyncio
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
async def query_with_retry(prompt, options):
results = []
async for message in query(prompt=prompt, options=options):
results.append(message)
return results
Q12: 如何在Jupyter Notebook中使用?
答:需要处理事件循环:
import nest_asyncio
nest_asyncio.apply()
# 然后正常使用
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def run():
async for message in query(prompt="Hello", options=ClaudeAgentOptions()):
print(message)
asyncio.run(run())
Q13: 可以保存和恢复会话吗?
答:支持。运行时会保存会话,你可以取得 session_id,再通过 resume 接着运行。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main():
session_id = None
async for message in query(prompt="先概括当前项目", options=ClaudeAgentOptions()):
if isinstance(message, ResultMessage):
session_id = message.session_id
if session_id is None:
raise RuntimeError("没有取得会话 ID,请先检查上一轮结果")
async for message in query(
prompt="继续,列出最值得优先检查的模块",
options=ClaudeAgentOptions(resume=session_id),
):
print(message)
if __name__ == "__main__":
asyncio.run(main())
保存 ID 方便再次恢复,但会话文件还须存在。把消息转成 str 存进 JSON 可以做日志,不能替代运行时的会话状态。保存范围、继续 / 分叉行为和存储位置请看官方会话文档。
Q14: TypeScript和Python SDK功能一样吗?
答:核心工作流相近,但接口、类型和部分功能支持会随两个 SDK 的版本分别演进。选择熟悉的语言后,按对应的 Python 或 TypeScript 官方参考写代码,别把一边的消息字段、选项名称或功能直接照搬到另一边。
Q15: 如何处理大文件?
答:不要依赖 Agent 一定自动读完整个大文件。Read 支持用 offset 和 limit 选择行范围,输出超限时需要缩小范围再读;也可以:
-
只读取需要的部分
-
使用Grep搜索而不是Read全文
-
拆分任务给多个子代理
Q16: SDK支持哪些AI模型?
答:支持Claude系列模型:
-
Opus:复杂推理任务,选择账号实际可用的型号
-
Sonnet:本章使用 claude-sonnet-5 演示
-
Haiku:本章使用 claude-haiku-4-5-20251001 演示
这不是固定的完整模型目录。可用型号取决于供应商、账号和运行时版本;不要把旧示例中的某个型号理解成一直最强或最便宜。
通过model参数指定:
options = ClaudeAgentOptions(model='claude-sonnet-5')
Q17: 如何测试自定义工具?
答:先沿用本章 3.3 节定义的 calculate 和 my_tools,再把下面的测试入口放在它们之后。直接调用 handler 只测试函数;后半段会调用模型,需要已配置认证并消耗额度。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def test_calculator():
# 3.3 节的 calculate 返回“计算结果:4”
result = await calculate.handler({"expression": "2+2"})
print(result)
assert result == {"content": [{"type": "text", "text": "计算结果:4"}]}
# 再通过模型验证工具发现与调用
async for message in query(
prompt="请使用 calculate 工具计算 2+2",
options=ClaudeAgentOptions(
mcp_servers={"tools": my_tools},
allowed_tools=["mcp__tools__calculate"],
),
):
print(message)
if __name__ == "__main__":
asyncio.run(test_calculator())
Q18: 如何处理API速率限制?
答:
-
添加请求间隔
-
使用指数退避重试
-
监控速率限制错误
import asyncio
async def rate_limited_query(prompts, delay=1.0):
for prompt in prompts:
async for message in query(prompt=prompt, options=options):
yield message
await asyncio.sleep(delay) # 请求间隔
Q19: 安全最佳实践有哪些?
答:
-
最小权限原则:只给需要的工具权限
-
输入验证:自定义工具要验证输入
-
不信任用户输入:Agent的prompt可能被注入
-
启用沙箱:Bash命令在沙箱中执行
-
使用Hooks过滤:阻止危险操作
-
监控日志:记录所有工具调用
Q20: 有官方示例代码吗?
答:有!
-
Python示例:https://github.com/anthropics/claude-agent-sdk-python/tree/main/examples
-
TypeScript示例:https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples
推荐从quick_start.py或quick_start.ts开始。
本课总结
核心知识点回顾
-
Agent SDK定位:把Claude Code的能力封装为可编程接口
-
query函数:核心API,返回流式消息
-
Agent Loop:接收→思考→使用工具→检查→继续/结束
-
Tools:Agent的能力来源,可以自定义扩展
-
Subagents:并行处理复杂任务
-
Hooks:在关键时刻自动执行自定义逻辑
最佳实践总结
场景
建议
模型选择
日常用Sonnet,复杂推理用Opus,简单任务用Haiku
权限控制
生产环境用最小权限,开发可以放宽
子代理
按职责拆分,控制并发与成本;限制以当前版本和配置为准
自定义工具
优先用SDK内置MCP服务器,简单高效
错误处理
使用try/catch,添加重试机制
下一步学习
完成本课后,建议继续学习:
-
MCP开发:深入学习MCP协议,创建更复杂的工具
-
Hooks高级应用:实现自动测试、自动格式化等工作流
-
企业集成:将Agent SDK集成到CI/CD流程
课程版本:V1.2
最后更新:2026年9月14日
作者:老金
版本历史
版本
日期
修改内容
V1.2
2026-02-26
更新模型配置示例;具体型号随后继续修订,当前可用范围见正文
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
初版发布
参考资料:
-
官方Agent SDK总览
-
官方Agent SDK Skills文档
-
GitHub Python SDK
-
GitHub TypeScript SDK
-
DataCamp教程
-
KDnuggets入门指南