Claude Agent SDK 是什么？把「Claude Code 的大脑」塞进你自己的代码库（基础篇）
导语
如果你看过我的《Claude Code 是什么》那篇，应该知道这货是 Anthropic 给开发者发的终端 AI 编程助手，能自己读文件、跑命令、改代码。但问题来了——它的能力全锁在那个命令行里，你想在自己的 Python/TypeScript 程序里调用这套能力，怎么办？
答案就是今天这篇的主角：Claude Agent SDK（GitHub 上叫 claude-agent-sdk-python，8 千星，MIT 协议，官方开源）。
一句话定位：把 Claude Code 的那套「代理循环 + 内置工具 + 上下文管理」打包成 Python 和 TypeScript 库，让你在自己进程里直接起一个能读文件、跑命令、搜网页、改代码的 Agent。openai 家的对应物是 OpenAI Agents SDK（我之前写过），Anthropic 这家给的是「原生拥抱 Claude Code 全家桶」的路子。
项目介绍
先说清楚它跟 Anthropic Client SDK 的区别,这是新手最容易绕晕的点：
- Client SDK（
anthropic包）：只给你 API 直连,你调messages.create(),返回了就完事。工具循环得自己写——while stop_reason == "tool_use":那套手动轮询。 - Agent SDK（今天这个）：工具循环 Claude 自己跑。你给它一句 prompt,它自动决定读哪个文件、跑哪条命令、改哪段代码,循环到任务结束才停。
官方文档那一段对照特别直白：Client SDK 要你自己实现 tool loop,Agent SDK 里 Claude handles it。
内置工具开箱即用，不用你实现任何工具执行逻辑：
| 工具 | 作用 |
|---|---|
| Read / Write / Edit | 读写和精确改文件 |
| Bash | 跑终端命令、脚本、git 操作 |
| Glob / Grep | 按模式找文件、按正则搜内容 |
| WebSearch / WebFetch | 联网检索和抓取网页 |
| Monitor | 盯后台脚本，每行输出当事件处理 |
| AskUserQuestion | 向用户提问选项 |
这些跟 Claude Code 命令行那套一模一样——SDK 是「同一套引擎,换了个可编程的壳」。
上手
Python 侧最简用法,几行就能起一个能改代码的 Agent：
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find and fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message) # Claude 读文件→找 bug→改代码
asyncio.run(main())
要点：
query()是一次性查询,适合批量处理、脚本自动化这种「输入已知、跑完就完」的场景。ClaudeSDKClient是双向交互客户端,能维护多轮会话上下文、支持打断（interrupt）、动态追问,适合做聊天界面或实时应用。allowed_tools是权限白名单——列出的工具自动放行,没列的你还能看permission_mode和can_use_tool再决定。想禁用某个工具用disallowed_tools。- 自定义工具、hooks（在代理生命周期节点插自己的回调,比如
PreToolUse做审计日志）都是纯 Python 函数,通过进程内 MCP server 实现,不用另开进程,好部署、好调试。
安装就一个命令 pip install claude-agent-sdk。TypeScript 版同理,@anthropic-ai/claude-agent-sdk。
实话
适合谁:想在 CI/CD 流水线里塞一个能自动改代码、跑测试的 Agent;或者给自家产品套一个「能动手」的 AI 能力,而不是只会闲聊的客服机器人。SDK 跑在你自己的进程和基础设施里,文件直接落在你的机器上,数据不出门——这个对很多企业场景是硬需求。
别被”免费”忽悠:代码开源是 MIT,但跑起来还是要 Anthropic API key,按 token 烧钱。Agent 类任务吃上下文烧得快,做好成本预算再上生产。
两条路认清楚:本地快速原型、依赖你文件系统的活儿,用 Agent SDK;要跑长任务、异步、又不想自己运维沙箱的,官方推荐迁到 Managed Agents（托管 REST API,Anthropic 帮你跑 agent 和 sandbox）。常见路径是 SDK 先原型,再迁托管。
坑:ClaudeSDKClient 目前不建议跨 asyncio 上下文复用同一个实例（内部有常驻任务组）;多任务、新架构折腾前,先翻官方 changelog（比如 ClaudeCodeOptions → ClaudeAgentOptions 的改名就坑过不少人）。
一句话总结:Claude Code 是给你人用的终端,Agent SDK 是把它拆给你代码用的零件库。搞懂它,你就看懂 Anthropic 把自家压箱底的 Agent 引擎开放给了谁。
—— 数码罗记 · godsun.pro
