一个开发者用一小段代码点亮一个会自己读文件、跑命令的智能体
我第一次想让 Claude 自动帮我改个 bug，按老办法调 messages.create，光是"让它读文件、跑命令、再按结果接着想"这套循环，就得自己写一大坨胶水代码。后来才知道官方早打包好了——这就是 Claude Agent SDK，把驱动 Claude Code 的那套工具、Agent 循环、上下文管理直接做成库，Python 和 TypeScript 都能用。
一句话：你负责给目标，工具的调用、循环、停机它全包了。 这篇我用 Python 从装包讲到跑通第一个能干活的 Agent，再把权限、自定义工具、Hooks、子 Agent、MCP 这几块过一遍。
它跟"调 Claude API"压根不是一回事
很多人第一反应是：这不就是套了层壳的 API 调用吗？还真不是。差别就在谁来跑工具循环。
用 Anthropic Client SDKhttps://platform.claude.com/docs/en/api/client-sdks（就是 messages.create 那套），你拿到的是直接的 API 通道：发提示词、自己实现工具执行、自己判断要不要再来一轮。代码长这样：
# Client SDK：工具循环得你自己写response = client.messages.create(...)while response.stop_reason == "tool_use": result = your_tool_executor(response.tool_use) response = client.messages.create(tool_result=result, **params)
换成 Agent SDK，这个 while 循环连同工具执行整个消失了，Claude 自己在内部转：
# Agent SDK：Claude 自动处理工具async for message in query(prompt="Find and fix the bug in auth.py"): print(message) # Claude 读文件、定位 bug、改掉它
我自己跑下来最直观的感受就是：Client SDK 是给你一支笔，Agent SDK 是给你一个已经会写字的人。读文件、跑命令、改代码这些内置工具开箱即用，不用你实现任何工具执行逻辑。
具体内置了哪些工具？文件相关的 Read、Write、Edit，执行类的 Bash，找文件的 Glob、搜内容的 Grep，联网的 WebSearch、WebFetch，还有盯后台脚本输出的 Monitor 和反问你的 AskUserQuestion。这套和你在 Claude Code 里用的是同一批。换句话说，你在命令行里习惯的那个 Claude，现在能直接嵌进自己的程序里跑了——同样的 Agent 循环、同样的上下文管理，只是接口从终端换成了一个函数。这也是它名字叫 Agent SDK 而不是某个 API 
还在更新，迭代很勤），注意要 Python 3.10 或更高版本——低于 3.10 装的时候会报 No matching distribution found，我就被这个坑了 5 分钟，python3 --version 看一眼就知道。
pip install claude-agent-sdkexport ANTHROPIC_API_KEY=your-api-key
API key 去 Consolehttps://platform.claude.com/ 拿。顺带一提，官方明确写了第三方不许用 claude.ai 的登录额度，老老实实用 API key（要走 Bedrock / Vertex / Azure 的话分别设 CLAUDE_CODE_USE_BEDROCK=1 这类环境变量）。
最小的能跑的例子，就这么几行：
import asynciofrom claude_agent_sdk import query, ClaudeAgentOptionsasync def main():async for message in query( prompt="What files are in this directory?", options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]), ):if hasattr(message, "result"): print(message.result)asyncio.run(main())
query() 返回的是一个异步迭代器，Claude 干活过程中的每条消息都会吐出来，最后那条带 result 的就是结论。这个 Agent 用 Bash 和 Glob 两个内置工具，自己就把当前目录列出来了。TypeScript 那边逻辑一模一样，包名是 @anthropic-ai/claude-agent-sdk，只是字段名换成驼峰 allowedTools，Node.js 18+ 即可。
Agent 收到目标后自己在读文件、跑命令、思考之间循环直到完成
给它配权限、塞自定义工具
让 Agent 能跑命令、改文件，第一个该想的是：它到底能动哪些东西。allowed_tools 
做一个只读的代码审查 Agent，给它读和搜的权限、不给写，就是这么干净：
import asynciofrom claude_agent_sdk import query, ClaudeAgentOptionsasync def main():async for message in query( prompt="Review this code for best practices", options=ClaudeAgentOptions( allowed_tools=["Read", "Glob", "Grep"], # 没有 Write/Edit/Bash，改不了任何东西 ), ):if hasattr(message, "result"): print(message.result)asyncio.run(main())
光用内置工具不够时，可以把自己的函数变成工具。用 @tool 装饰器声明，再用 create_sdk_mcp_server 打包成一个进程内的 MCP server 挂上去：
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient@tool("greet", "Greet a user", {"name": str})async def greet_user(args):return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}server = create_sdk_mcp_server(name="my-tools", version="1.0.0", tools=[greet_user])options = ClaudeAgentOptions( mcp_servers={"tools": server}, allowed_tools=["mcp__tools__greet"], # 工具名规则：mcp__<server>__<tool>)async with ClaudeSDKClient(options=options) as client:await client.query("Greet Alice")async for msg in client.receive_response(): print(msg)
这里有两个细节值得记一下。一是工具的全名是 mcp__tools__greet 这种 mcp__<server名>__<工具名> 的拼法，allowed_tools 里要写全名。二是 ClaudeSDKClient 和 query() 不一样——它是给多轮交互用的，可以一直 client.query() 接着聊，query() 更适合一次性任务。
权限这块还有几个旋钮值得知道。permission_mode 控制整体放行策略，比如设成 "acceptEdits" 就是自动接受文件编辑、不再逐个弹确认；和 allowed_tools 相对的还有 disallowed_tools，专门用来黑名单掉某些危险操作。ClaudeAgentOptions 上还能配 system_prompt（改系统提示词）、max_turns（按文档可限制 Agent 最多运行的轮数）、cwd（工作目录）这些，基本上你在 Claude Code 里能调的，这里都有对应字段。
还有个我后来才发现挺香的点：SDK 默认会加载 .claude/ 目录下的配置——当前目录和 ~/.claude/ 里的 Skills、自定义命令、CLAUDE.md 记忆都会自动读进来。意思是你给 Claude Code 写的那套项目规则，SDK 跑的时候直接复用，不用再抄一遍。想限制只读哪些来源，用 setting_sources（TypeScript 是 settingSources）收一下就行。
Hooks、子 Agent、MCP：四个你迟早用到的能力
把基础跑通之后，真正让 Agent SDK 好用的是这几块能力。我挑最常用的过一遍，每个都几行代码的事。
Hooks 是在 Agent 生命周期的关键点插自己的回调，能验证、记录、拦截或者改写行为。可用的钩子有 PreToolUse、PostToolUse、Stop、SessionStart、SessionEnd、UserPromptSubmit 等等。比如把所有文件改动记到审计日志：
import asynciofrom datetime import datetimefrom claude_agent_sdk import query, ClaudeAgentOptions, HookMatcherasync def log_file_change(input_data, tool_use_id, context): file_path = input_data.get("tool_input", {}).get("file_path", "unknown")with open("./audit.log", "a") as f: f.write(f"{datetime.now()}: modified {file_path}\n")return {}async def main():async for message in query( prompt="Refactor utils.py to improve readability", options=ClaudeAgentOptions( permission_mode="acceptEdits", # 自动接受文件编辑 hooks={"PostToolUse": [HookMatcher(matcher="Edit|Write", hooks=[log_file_change])]}, ), ):if hasattr(message, "result"): print(message.result)asyncio.run(main())
子 Agent（Subagents） 是派专门的小 Agent 干专项活，主 Agent 分发任务、它们回报结果。用 AgentDefinition 定义，记得 allowed_tools 里要带上 "Agent"，不然子 Agent 的调用不会被自动批准：
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinitionoptions = ClaudeAgentOptions( allowed_tools=["Read", "Glob", "Grep", "Agent"], agents={"code-reviewer": AgentDefinition( description="Expert code reviewer for quality and security reviews.", prompt="Analyze code quality and suggest improvements.", tools=["Read", "Glob", "Grep"], ) },)
MCP 让 Agent 接外部系统——数据库、浏览器、各种 API。比如挂上 Playwright MCP serverhttps://github.com/microsoft/playwright-mcp 就有了浏览器自动化能力，配置就是一行：mcp_servers={"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}}。注意这跟前面 create_sdk_mcp_server 那种进程内工具不一样——这里是连一个外部 MCP 进程，社区现成的 MCP server 有好几百个，能直接拿来用。
Sessions 则负责跨多轮记住上下文。它的价值在于 Claude 会记得读过哪些文件、做过什么分析。用法是第一次 query 从 SystemMessage（subtype == "init"）里取出 session_id，下一次用 ClaudeAgentOptions(resume=session_id) 接着上文继续。我拿它做过一个场景：第一轮让它"读一下认证模块"，第二轮直接问"现在找出所有调用它的地方"，因为 session 续上了，那个"它"指的是谁 Claude 自己门清，不用我再把上下文复述一遍。子 Agent 的消息里还带 parent_tool_use_id，想追踪哪条消息属于哪个子任务也对得上。
claude-agent-sdk-python 官方仓库 README
到底什么时候该用 SDK，又有什么局限
不是所有场景都该上 SDK。官方自己给了一张对照，我觉得挺实在：交互式开发、一次性任务用 Cla
verview 更顺手；CI/CD、生产自动化、要塞进自己应用里的，才轮到 SDK。很多团队两个都用——日常开发用 CLI，上生产用 SDK，工作流之间能直接平移。
还有个容易混的：Agent SDK 和 Managed Agentshttps://platform.claude.com/docs/en/managed-agents/overview 是两回事。Agent SDK 是库，跑在你自己的进程和机器上，session 以 JSONL 存在你的文件系统里；Managed Agents 是 Anthropic 托管的 REST API，连沙箱带 session 都给你托管。常见路径是先用 SDK 本地把原型跑通，要上规模再迁到 Managed Agents。
# 本地原型：Agent 直接在你的文件系统上干活async for message in query( prompt="Fix the bug in auth.py", options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),): print(message)
要说局限，我自己踩到的是：Agent 自主跑工具这件事，权限没收好就是把双刃剑——permission_mode="acceptEdits" 一开，它真就自己改文件了，所以生产环境我宁可白名单收紧到只读，再按需逐个放开。这点别嫌麻烦，等它在不该动的地方动了手你就知道值了。
另一个要心里有数的是成本和不确定性。Agent 自己决定跑几轮工具，意味着一次任务到底烧多少 token、跑多久，没法像普通 API 调用那样精确预估，所以 max_turns 该设就设，给它一个上限。还有它毕竟是模型在做决策，同一个 prompt 两次跑出来的步骤未必完全一样——做 demo 很惊艳，但要塞进对稳定性敏感的生产流程，就得在外面包一层校验和重试，别指望它每次都一步到位。把这两件事想清楚，再决定哪段流程交给它自主跑、哪段还是自己写死，是我现在上手任何 Agent 项目的第一步。
写在最后
Claude Agent SDK 真正省掉的，是你自己写工具循环、管上下文这些重复劳动——给目标、配权限、挂工具，剩下的交给那套和 Claude Code 同源的引擎。
建议先收藏再看，上面权限配置、@tool 自定义工具、Hooks 这几段都需要照着敲一遍才记得住。
下一步很简单，跑这一条把环境装好，照着最小例子改个你自己的 prompt 试试：
pip install claude-agent-sdk && export ANTHROPIC_API_KEY=your-api-key
想看更完整的真实 Agent，官方的 示例仓库https://github.com/anthropics/claude-agent-sdk-demos 里有邮件助手、调研 Agent 这些可以直接抄。
