Claude Agent SDK 怎么用?用 Python / TypeScript 搭建 AI Agent 入门教程(2026)
Claude Agent SDK 怎么用?本文讲清 Claude Agent SDK 是什么、与 Claude API 的区别,演示 Python 与 TypeScript 安装和 query() 用法,配置内置工具、权限模式、自定义工具、会话与成本统计,并附从 Claude Code SDK 迁移的注意事项和常见问题。
SupaStore 开发者体验组 ·

Claude Agent SDK 是 Anthropic 把 Claude Code 的智能体能力打包成的开发库:你写一个提示词和几行配置,Agent 就能自己读写文件、执行命令、搜索网页,并循环调用工具直到完成任务。它支持 Python 和 TypeScript,适合用来搭建代码助手、运维机器人、数据分析 Agent 等应用。
本文讲清 Claude Agent SDK 和 Claude API 的区别,演示 Python、TypeScript 的安装与第一个 Agent,再介绍工具、权限、自定义工具、会话和成本统计。
Claude Agent SDK 和 Claude API 有什么区别
| 对比项 | Claude API(Messages API) | Claude Agent SDK |
|---|---|---|
| 本质 | 一次请求、一次回答 | 内置 Agent 循环,自动多轮调用工具 |
| 工具 | 需要自己定义并执行 | 自带读写文件、执行命令、搜索等工具 |
| 上下文管理 | 自己维护对话历史 | SDK 自动管理会话 |
| 适合 | 问答、分类、提取、生成 | 需要自主完成多步任务的 Agent |
简单说:只是让模型回答问题,用 Claude API 就够了(入门见《Claude API 调用教程:Python 接入 Claude API 完整示例》);需要模型自己动手完成一系列操作,用 Claude Agent SDK 能省掉大量循环和工具执行的代码。自己实现工具调用的方法见《Claude 工具调用怎么用?》。
安装 Claude Agent SDK
Python(需要 Python 3.10 及以上):
pip install claude-agent-sdk
TypeScript(需要 Node.js 18.14 及以上):
npm install @anthropic-ai/claude-agent-sdk
两个 SDK 都自带了 Claude Code 的运行程序,大多数情况下不需要另外安装 Claude Code。
然后设置 API Key:
export ANTHROPIC_API_KEY="your-api-key"
SDK 不会自动读取 .env 文件,需要的话请自己用 dotenv 加载。Key 的获取方法见《Claude API Key 怎么获取?》。
第一个 Agent:Python 示例
下面的 Agent 会自己找到并修复 utils.py 里的 bug:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
async for message in query(
prompt="检查 utils.py 中会导致崩溃的 bug,并修复它们",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)
elif hasattr(block, "name"):
print(f"调用工具:{block.name}")
elif isinstance(message, ResultMessage):
print(f"完成:{message.subtype}")
asyncio.run(main())
query() 会以流的形式不断返回消息:AssistantMessage 是 Claude 的回复和工具调用,ResultMessage 是任务结束时的结果。subtype 为 success 表示正常完成,error_max_turns 表示达到了最大轮数。
TypeScript 示例
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "检查 utils.py 中会导致崩溃的 bug,并修复它们",
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
},
})) {
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) console.log(block.text);
else if ("name" in block) console.log(`调用工具:${block.name}`);
}
} else if (message.type === "result") {
console.log(`完成:${message.subtype}`);
}
}
TypeScript 的选项名是驼峰写法:allowedTools、permissionMode、maxTurns、systemPrompt。
常用配置项
| Python | TypeScript | 作用 |
|---|---|---|
allowed_tools |
allowedTools |
允许 Agent 使用的工具,如 Read、Edit、Bash、Glob、WebSearch |
permission_mode |
permissionMode |
权限模式,决定改文件、执行命令前是否需要确认 |
system_prompt |
systemPrompt |
系统提示词 |
max_turns |
maxTurns |
最大轮数,防止 Agent 无限循环 |
max_budget_usd |
maxBudgetUsd |
预算上限(客户端估算) |
model |
model |
使用的模型 |
cwd |
cwd |
Agent 的工作目录 |
permission_mode 常用的取值有 default(敏感操作需要确认)、acceptEdits(自动接受文件修改)和 plan(只做规划不执行)。给 Agent 的权限应当"够用就好",尤其是在服务器上运行时,不要随意放开执行命令的权限。权限的概念和 Claude Code 一致,见《Claude Code 权限怎么设置?》。
自定义工具
除了内置工具,还可以把自己的函数注册成工具。Python 用 @tool 装饰器定义工具,再用 create_sdk_mcp_server 打包:
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions
@tool("get_order", "根据订单号查询订单状态", {"order_id": str})
async def get_order(args):
status = "已发货" # 这里换成你的数据库或接口查询
return {"content": [{"type": "text", "text": f"订单 {args['order_id']}:{status}"}]}
orders = create_sdk_mcp_server(name="orders", version="1.0.0", tools=[get_order])
options = ClaudeAgentOptions(
mcp_servers={"orders": orders},
allowed_tools=["mcp__orders__get_order"],
)
注册后,工具名的格式是 mcp__服务器名__工具名,要加到 allowed_tools 里 Agent 才能调用。MCP 的概念见《Claude Code MCP 怎么配置?》。
多轮对话与成本统计
- 单次任务用
query():每次调用默认是一个新会话,适合一次性的自动化任务; - 多轮对话用
ClaudeSDKClient:在同一个会话里连续交互,支持中途打断,适合聊天类应用; - 恢复会话:通过
resume选项传入会话 ID,可以在之前的上下文上继续。
成本方面,Python 的 ResultMessage 带有 total_cost_usd 字段,记录本次任务的累计花费。流式模式下它是累计值,读最后一条结果即可,不要把每条加起来。
从 Claude Code SDK 迁移的注意事项
Claude Agent SDK 由 Claude Code SDK 更名而来:
- 包名:Python 从
claude-code-sdk改为claude-agent-sdk,TypeScript 从@anthropic-ai/claude-code改为@anthropic-ai/claude-agent-sdk; - Python 的
ClaudeCodeOptions改名为ClaudeAgentOptions; - 默认系统提示词变了:新版不再默认使用 Claude Code 的系统提示词。想保持原来的行为,需要显式指定
system_prompt={"type": "preset", "preset": "claude_code"}。
通过中转站使用 Claude Agent SDK
Agent SDK 底层运行的就是 Claude Code,Claude Code 读取的 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 等环境变量,可以通过系统环境变量或 env 选项传给 Agent。地址的填写方法与本地 Claude Code 相同,见《Claude API 中转怎么用?国内 Claude Code 中转站配置教程》。官方 SDK 文档没有专门说明这种用法,正式上线前请先用简单任务验证。
常见问题 (FAQ)
Q: Claude Agent SDK 免费吗?
答: SDK 本身免费开源,但 Agent 每一轮都会调用模型,按 Token 计费。Agent 任务往往要多轮调用,建议用 max_turns 和 max_budget_usd 控制单次任务的上限。
Q: Claude Agent SDK 可以用 Claude Pro 或 Max 订阅登录吗?
答: 不可以用于对外提供的产品。官方说明,除非事先获得批准,第三方开发者不能在基于 Agent SDK 的产品中提供 claude.ai 登录或使用订阅额度,应使用 API Key。
Q: Agent SDK 和 Claude Code 有什么关系?
答: Claude Code 是一个现成的命令行编程工具,Agent SDK 则把同样的 Agent 循环、工具和上下文管理能力开放成开发库,让你把它嵌入自己的程序。
Q: query() 和 ClaudeSDKClient 怎么选?
答: 一次性任务、脚本和定时任务用 query();需要和用户来回对话、根据上一轮结果决定下一步,或者需要中途打断时,用 ClaudeSDKClient。