本篇目录
本文按 Claude Agent SDK 官方文档整理,2026 年 10 月核对。如有出入,以官方的 Agent SDK 概览和快速上手为准。

Agent SDK 是什么
前面七课,都是你和 Claude Code 对话,让它干活。Agent SDK 换了个方向:把 Claude Code 的「大脑和双手」做成一个库,让你写进自己的程序里。
Claude Code 能读文件、改文件、跑命令、查资料,还会自己决定下一步做什么,这一整套循环就是 Agent SDK 提供的东西。你不用自己实现「调用工具 → 看结果 → 决定下一步」这些逻辑,写几行代码就能得到一个会干活的 AI 助手。
它有 Python 和 TypeScript 两个版本,用法几乎一样。上一课的 GitHub Action,底层用的就是它。

什么时候用它
- 只是自己写代码:用 Claude Code 命令行或编辑器插件就够了,不需要 SDK
- 想做一个自动跑的工具:比如每晚自动检查日志、批量整理文档、给内部系统加一个能动手的助手,用 SDK
- 只要一问一答的文字:直接调用 Claude API 更简单,SDK 的长处在于能自己用工具、多步完成任务
准备工作
- Python 3.10 以上,或 Node.js 18 以上
- 一个 Claude Console 账号,在里面创建一个 API Key
SDK 自带了 Claude Code 的运行程序,大多数情况下不用另外安装 Claude Code。
第一步:建项目、装 SDK
Python(用 pip):
mkdir my-agent && cd my-agentpython3 -m venv .venvsource .venv/bin/activatepip install claude-agent-sdkTypeScript:
mkdir my-agent && cd my-agentnpm init -ynpm pkg set type=modulenpm install @anthropic-ai/claude-agent-sdknpm install --save-dev tsx然后在同一个终端里设置 API Key:
export ANTHROPIC_API_KEY=你的 API KeySDK 只从环境变量里读这个 Key,不会自动读 .env 文件。如果你习惯用 .env,要自己先加载。
第二步:准备一个有 bug 的文件
在 my-agent 文件夹里新建 utils.py,故意留两个会崩溃的问题:
def calculate_average(numbers): total = 0 for num in numbers: total += num return total / len(numbers)
def get_user_name(user): return user["name"].upper()传入空列表时,第一个函数会除以零;传入 None 时,第二个函数会报错。
第三步:写一个会修 bug 的助手
新建 agent.py:
import asynciofrom 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())用 TypeScript 的话,新建 agent.ts:
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}`); }}第四步:运行
python agent.pyTypeScript 用 npx tsx agent.ts。
你会看到它边想边做:先读 utils.py,找出两个问题,再动手改,最后打印 完成:success。打开 utils.py,会看到空列表和空用户都有了保护。
如果报 Not logged in 或 Invalid API key,多半是 ANTHROPIC_API_KEY 没在当前这个终端里设置。
看懂这段代码
整段代码只有三个关键部分:
- query:入口。它启动一个循环,Claude 每想一步、每用一次工具,都会吐出一条消息,你用
async for一条条接住 - prompt:你要它做的事。用哪些工具、按什么顺序,它自己决定
- options:给它定规矩。
allowed_tools列出不用问就能用的工具,permission_mode="acceptEdits"表示改文件不用问
循环里的那些判断,只是把消息里人能看懂的部分打印出来。去掉它们,你会看到完整的原始消息,调试时很有用。
换几个参数试试
工具决定了它能做什么,按需加减:
- 只读分析:
Read、Glob、Grep - 分析并修改:
Read、Edit、Glob - 还能跑命令:再加上
Bash,就可以让它「写单元测试、运行、把失败的修好」 - 能上网查:再加上
WebSearch
给它一个固定身份,用 system_prompt(TypeScript 里是 systemPrompt):
options = ClaudeAgentOptions( allowed_tools=["Read", "Edit", "Glob"], permission_mode="acceptEdits", system_prompt="你是一位资深 Python 工程师,代码遵循 PEP 8 规范。",)再往后,SDK 还支持第 5 课讲过的那些扩展:MCP 连外部系统、钩子、子代理、Skill,以及多轮对话的会话管理,都在官方文档里有详细说明。
做成产品前要知道的
- 认证用 API Key:给别人用的产品,必须用 API Key(或 Amazon Bedrock、Google Cloud 等云平台)认证,不能让用户用 claude.ai 账号登录,除非事先获得 Anthropic 批准
- 名字别叫 Claude Code:你的产品可以写「Powered by Claude」,但不能叫 Claude Code,也不能模仿它的品牌
- 权限要收紧:自动运行的程序没人盯着,只给它完成任务需要的工具,
Bash这类能力能不给就不给
这一课学到的
- Agent SDK 把 Claude Code 的工具和自主循环做成了 Python / TypeScript 库
- 安装:
pip install claude-agent-sdk或npm install @anthropic-ai/claude-agent-sdk,用环境变量ANTHROPIC_API_KEY认证 - 核心就是
query(prompt, options),用async for接收它每一步的消息 allowed_tools决定它能做什么,permission_mode决定要不要问你- 做成给别人用的产品时,用 API Key 认证,不能叫 Claude Code
本系列
「Claude Code 上手」一共 8 课:前 5 课是基础,第 6 到 8 课是进阶篇,建议按顺序看:
- 第 1 课 · 第一次用 Claude Code:从空文件夹到能打开的小网页
- 第 2 课 · 写好 CLAUDE.md:让 Claude Code 记住项目规矩
- 第 3 课 · 权限模式与计划模式:放手多少由你定
- 第 4 课 · 管好上下文:清空、压缩、回退和接着聊
- 第 5 课 · 扩展 Claude Code:MCP、Skill、子代理和钩子
- 第 6 课 · 在 VS Code 和 JetBrains 里用 Claude Code
- 第 7 课 · GitHub Actions:在评论里 @claude 让它干活
- 第 8 课 · Claude Agent SDK 入门:写一个会修 bug 的助手
还没装好?先看 10 分钟装好 Claude Code。