拿大模型 API 写一个问答机器人，这件事我闭着眼睛都能完成：一个 HTTP 请求、一段 system prompt、一条用户消息，回答就返回了。但一旦要让 AI 真正“干活”——查数据库、改文件、跑测试、调外部服务——普通 API 调用立刻顶不住。原因很简单：API 只给你一次“思考＋回复”的瞬间能力，而干活需要的是“思考 → 行动 → 观察结果 → 再思考”的循环。Claude Agent SDK 正是冲着这个缺口来的：它把模型、工具、循环和会话状态打包成一个可编程运行时，让我可以用代码直接控制一个 AI 助手去执行多步任务。这篇文章我会把 Agent 循环的原理讲透，再带你从零搭环境、定义自定义工具，最后用一个“自动整理代码仓库”的实战案例收尾，并聊聊生产化改造时的步数、权限、成本和那些文档里不会写的坑。适合已经写过 Claude API 调用、现在想往 agent 方向走的人，也适合手里有一堆重复杂活、想找一个可靠框架来承接的开发者。
1. 从问答接口到干活循环：Agent SDK 到底补上了什么
1.1 普通 API 调用缺的不是“智能”，是“循环”
很多人在第一次接触 Agent 这个概念时，都会有个困惑：我不就是用 prompt 让模型去调用工具吗？Messages API 本身就支持 tool use，我自己写个 if-else 也能把工具结果塞回去，为什么要多一个 SDK？
我早期也这么干过。自己维护一个 while 循环，判断响应里有没有 tool_use 块，有就执行本地函数，再把结果拼成新的 user 消息发回去。跑通一个 demo 不难，难在它只解决了“单轮工具调用”。真实任务往往是这样：模型要先列目录，看到一堆文件后决定读某个文件，读完又发现需要去查 git 历史，查完又回来改写文件，最后还要验证结果。这个链条可能有七八轮，每一轮都要处理截断、错误、并行调用、上下文膨胀。更麻烦的是，模型每次重试都会把整段历史重新送进去，token 消耗成倍增长。
普通 API 调用的本质缺陷是：它没有“状态”。每次请求都是一次独立判断，而 Agent 需要的是一个持续运转、能记住自己刚才做过什么、并根据结果调整下一步的执行器。所谓 Agent 化，不是让模型变得更聪明，而是给模型配上一套可以持续行动的循环。Claude Agent SDK 核心就是把这个循环做成标准件，并且把循环里的每一步都开放给你观测和干预。
1.2 Agent 循环的五个阶段
我习惯把 Agent 的一次完整任务理解成五段式循环，理解了它，你基本就理解了整个 SDK。
第一段是“注入”。SDK 把系统提示词、工具定义、历史消息和当前用户指令整理成一次大模型的请求。第二段是“决策”。模型返回两类东西之一：要么是普通文本，表示它认为任务已经完成；要么是一个或多个 tool_use 块，表示它希望调用某个工具，并附带结构化参数。第三段是“执行”。SDK 拿到 tool_use 后，找出对应的本地函数或外部服务，把参数传进去运行。第四段是“反馈”。执行结果被包装成 tool_result 消息，连同工具的标识 ID 一起送回模型，模型能看到“你刚才那步做完了，结果是这个”。第五段是“回到第二段”。模型根据结果继续决策，直到它觉得自己干完了，输出最终文本为止。
这里有个容易误解的点：工具调用本身不复杂，复杂的是“多轮”。一个循环里可能有三次、八次甚至二十次工具调用，模型需要根据上一次的结果修正下一次的参数。比如它第一次用 Bash 列目录发现文件不在预期位置，第二次就会换一个路径去查。这种自主修正，就是 Agent 和普通“函数调用 demo”的本质区别。SDK 把这些细节全部管理起来了，包括并行 tool_use 的执行、工具返回过大时的截断、会话历史的自动维护。
1.3 它在整个工具链里的位置
如果你用过 Claude Code 的命令行交互版，可以把 Agent SDK 理解成它的“可编程内核”。命令行交互版适合人在终端里实时对话，而 Agent SDK 适合把同一套 Agent 能力嵌进你自己的服务、定时任务或自动化流水线里。两者共用底层的一整套能力：内置工具（Bash、读文件、写文件、编辑）、MCP 服务连接、权限控制、会话恢复。
再往下对比，Messages API 是“一锤子买卖”，适合你明确知道自己要发什么、收什么。Agent SDK 是“按项目承包”，它承载的是不确定性较高的多步任务：你告诉它目标，它在循环里自己摸索路径。中间还有一层就是 MCP，它解决的是“工具从哪里来”的问题。MCP 服务可以把外部系统（数据库、浏览器、内部系统）包装成标准工具，Agent SDK 直接消费这些工具。所以你可以这么理解：MCP 是给 Agent 装新器官，Agent SDK 是给 Agent 装身体，模型是大脑，而你是那个负责设定边界和验收结果的人。
2. 环境准备与第一个能自主调用工具的 Agent
2.1 安装和鉴权里两个容易翻车的细节
先说我踩过的第一个坑：Node 版本。Agent SDK 是 TypeScript 优先的，依赖一些比较新的运行时特性，我最早在 Node 16 的环境里装，启动时直接报语法错误。后来统一换到 Node 18 以上才稳定。如果你用的是 npm，安装很简单，一条命令：
npm install @anthropic-ai/claude-agent-sdk鉴权方面，SDK 默认从环境变量读取 API 密钥。建议在项目根目录放一个.env文件，用 dotenv 加载：ANTHROPIC_API_KEY=sk-ant-...。这里有两个细节：一是密钥千万别写进代码仓库，我见过不止一次有人把本地测试用的密钥提交上去，然后账单爆炸；二是如果你在团队协作，最好通过密钥管理服务注入环境变量，而不是每个人各自复制一份。另外，SDK 跑起来会真实消耗 token，本地调试时建议先给账号设置好预算上限，别问我为什么强调这一点。
2.2 最小可运行示例：让 Agent 自己决定用什么工具
我先把话说明白：下面代码基于我常用的 SDK 版本写法，这类库迭代很快，小版本之间字段可能微调。你跑之前先看一眼node_modules里自带的类型定义，实在对不上就按编辑器提示改，这比硬记文档里的例子更稳。
先做一个不接任何自定义工具的版本，让 Agent 用内置的 Bash 工具去完成一个需要“观察后行动”的任务：
import "dotenv/config"; import { Agent } from "@anthropic-ai/claude-agent-sdk"; const agent = new Agent({ prompt: "你是一位可靠的开发助手。回答前先观察工作区，需要验证时使用工具，不要凭空猜测。", }); async function main() { for await (const event of agent.start({ prompt: "列出当前目录下所有文件，按体积从大到小排序后输出前 10 个。", })) { if (event.type === "stream_event") { const text = event.event.content_block_delta.delta?.text; if (text) process.stdout.write(text); } } } main().catch((e) => { console.error(e); process.exit(1); });这个例子看着简单，但已经包含了 Agent 的核心体验：我并没有告诉它“用 Bash 运行 ls”，只说了一个目标。它会自己决定调用 Bash，自己决定怎么组装命令，然后把结果读一遍再输出。你观察事件流就能看到，模型先输出一段“让我看看目录下有什么”，然后产生一个 tool_use，SDK 执行工具，模型拿到结果后再写最终回答。这就是编程控制 AI 助手的起点：你控制的是目标和边界，而不是每一步的具体动作。
2.3 事件流里有哪些值得关注的信号
第一次跑通 Agent 后，建议别急着加功能，先花十分钟把事件流打出来看看。SDK 默认暴露的是一系列流式事件，我在调试时最常关注这几类：
| 事件类型 | 出现时机 | 调试时的价值 |
|---|---|---|
| stream_event | 模型边生成边推送 | 看模型“在想什么”，实时输出文本 |
| tool_event | 某个工具开始/结束执行 | 确认模型的行动路径、工具参数 |
| message_event | 一整条消息完成 | 拿到完整消息和 token 用量 |
| session_event | 会话建立/更新 | 拿到 session_id，用于后续恢复 |
| result_event | 多子代理任务的局部结果 | 观察子代理返回内容 |
我一般会在本地写一个小函数，把 tool_event 单独高亮打印，因为它能非常直观地暴露模型是不是在同一个工具上反复打转。如果看到它连续三次用几乎一样的参数调用同一个工具，说明提示词或者工具描述写得有问题，得尽早干预。这个观测习惯，在你做生产化改造时会变成救命稻草。
另外，这类事件类型的字段名在各版本间有变动。一个很实用的办法是：先跑一个空任务，把完整事件对象JSON.stringify打印出来，对照实际结构再写你的解析逻辑。官方文档永远是对的，但“你本地装到的那个版本”才是你真正要面对的。
3. 自定义工具：把外部能力交到 Agent 手里
3.1 定义第一个自定义工具
内置工具再全，也不可能覆盖你系统的专有能力。比如你希望 Agent 能查你们内部的订单状态，或者给你自己的后端接口发请求，这时就需要自定义工具。SDK 提供了类似装饰器的定义方式，我常用的写法是这样：
import { Agent, defineCustomTool } from "@anthropic-ai/claude-agent-sdk"; const queryOrderStatus = defineCustomTool({ name: "query_order_status", description: "查询内部订单系统的订单状态。传入订单号，返回当前状态和最近一次更新时间。", inputSchema: { type: "object", properties: { orderId: { type: "string", description: "订单号，格式如 ORD-2025-0001" }, }, required: ["orderId"], }, handler: async ({ orderId }) => { const result = await fetchOrderStatus(orderId); // 你自己的业务逻辑 return { type: "success", data: { orderId, status: result.status, updatedAt: result.updatedAt, }, }; }, }); const agent = new Agent({ prompt: "你是一个售后助手，查询订单时先确认订单号格式正确。", tools: { query_order_status: queryOrderStatus }, });整个工作流程很简单：模型在决策阶段看到工具的名字、描述和 inputSchema，判断“我需要查订单”，于是生成一个带参数的 tool_use；SDK 拿到参数后调用你的 handler；handler 的返回值会被序列化回传给模型。你在 handler 里写什么业务逻辑都行，调用数据库、请求内网接口、操作文件系统，对模型来说它只是“一个工具”。
3.2 输入 Schema 是写给模型看的“说明书”
这是我认为自定义工具里最值得花功夫的地方。很多人把 inputSchema 当成后端接口的校验参数来写，只写类型，不写说明。但你要记住：这个 Schema 的第一个读者不是你的后端代码，而是大模型。模型根据字段描述来决定传什么值，描述写得越模糊，它给出的参数就越离谱。
举个例子，一个订单查询工具，如果你只写orderId: string，模型很可能传一个“用户的订单号”进去，而你的系统实际要的是带前缀的标准格式。我建议在每个字段描述里带上格式示例和取值规则，甚至可以写“如果用户只提供了部分信息，不要猜测，询问完整条件”。必要的时候，用 enum 把可选值框死：
properties: { timeRange: { type: "string", enum: ["today", "this_week", "this_month"], description: "查询范围，必须是这三个值之一", }, }这个习惯的价值在长期运行里体现得很明显：模型在大部分情况下都会严格遵循枚举和格式，因为描述给了它足够强的约束信号。工具越“笨”、越确定，Agent 整体就越可靠。
3.3 工具失败之后的兜底设计
自定义工具在执行阶段一定会出错：接口超时、数据不存在、权限不足。这时候最忌讳的做法是让 handler 直接抛异常，因为异常会中断整个循环，模型拿不到失败原因，你的任务也就戛然而止。更合理的做法是把失败本身包装成返回值的一部分，让模型知道发生了什么、有没有别的路径可走。
我常用的模式是返回一个带status字段的结构，成功和失败都走同一个出口：
handler: async ({ orderId }) => { try { const result = await fetchOrderStatus(orderId); return { type: "success", data: result }; } catch (e) { return { type: "error", data: { message: `订单 ${orderId} 查询失败：${e.message}，可能原因：单号格式错误或系统维护中` }, }; } }模型读到这个错误信息后，通常有两种反应：要么纠正参数重新调用，要么直接告诉用户“当前无法查询，可能是系统维护”，而不会陷入沉默或幻觉。你还可以在 description 里明确写“查询失败时尝试一次后停止，不要重复调用”，这能有效降低模型在同一个坏工具上反复重试的概率。另一个需要注意的点是工具返回体量。如果你的工具返回一个几万字符的日志，模型读起来又慢又贵，甚至直接触发上下文截断。好的做法是在 handler 里做好摘要和切片，只回传关键字段，细节留在日志文件里，让模型需要时再主动去查。
4. 实战：用 Agent 自动整理一个混乱的代码仓库
4.1 先把任务拆成工具集
理论讲再多，不如跑一个真实任务。我拿一个常见的场景举例：接手了一个历史项目，仓库里散落着临时脚本、调试日志、编译产物，文档目录里有好几个命名混乱的旧版本说明。人工整理很烦，而且每个人整理完的标准还不一样。用 Agent 来做，好处是它可以边看边决策，而且每次整理的决策过程都能留下记录。
我没有直接把 Bash、Write、Edit 全部开放给它，而是定义了一组更贴近任务语义的自定义工具，让模型在有限的、安全的操作集合里工作：
| 工具名 | 作用 | 安全约束 |
|---|---|---|
| list_directory | 列出目录下的文件与大小 | 只读，不进入 node_modules |
| read_text_file | 读取指定文本文件前若干行 | 只读，限制单次读取大小 |
| create_directory | 新建目录 | 限制新建路径必须在项目内 |
| move_file | 移动文件到目标目录 | 禁止移动隐藏配置 |
| delete_file | 删除指定文件 | 必须二次确认文件名匹配 |
| write_report | 把整理报告写入指定文档 | 只允许写入 docs 目录 |
每个工具的描述里我都写了它适合什么场景、禁止什么场景。这一层约束非常关键：模型不会主动越界，但你要把边界画出来。它在这个工具集里能做的所有事情，都是可审计、可回滚的，这就让整个整理流程可以放心挂到自动化任务里。
4.2 运行实录：Agent 是怎么一步步干完的
下面是这个任务的一次简化运行记录，省略了模型的长篇文本，只看工具调用链路就能感受到“循环”的节奏：
工具调用：list_directory({ path: "." }) → 发现根目录有 temp_data.csv、app.log、backup/、docs/、src/ 工具调用：read_text_file({ path: "temp_data.csv", lines: 5 }) → 确认是某次调试临时导出的数据 工具调用：create_directory({ path: "archive/temp" }) 工具调用：move_file({ source: "temp_data.csv", target: "archive/temp/temp_data.csv" }) 工具调用：list_directory({ path: "docs" }) → 发现 2024 旧版说明、2025 新版说明、README_backup.md 工具调用：read_text_file({ path: "docs/README_backup.md", lines: 10 }) → 内容与主 README 重复，判断为遗留备份 工具调用：delete_file({ path: "docs/README_backup.md" }) → 删除前模型自己停下来，输出“确认这个文件已不被任何入口引用” 工具调用：write_report({ path: "docs/reorganize_report.md", content: "..." }) → 写入完整整理报告注意第三步到第四步之间，模型没有问我要不要执行，因为它在系统提示词里已经被告知“这是一个自动化整理任务，遇到明显分类清晰的项可以直接执行”。但它删除文件前会先读内容验证，这个验证动作不是我在代码里写死的，而是模型根据“安全约束”描述自己形成的判断。这是 Agent 和普通脚本最大的区别：脚本只会按你写的规则执行，Agent 会在规则之内动态调整自己的执行策略。
这个案例跑下来大概花了 6 分钟、四十多次工具调用，比人工快，但更重要的是过程留痕。整理完的仓库长什么样、每个文件为什么去了那里，全部写在报告里。对团队协作来说，这种可解释性比“快”更有价值。
4.3 会话恢复与 Checkpoint：干到一半断了怎么办
长任务最烦的问题就是中断：网络抖动、进程被杀、API 报错。以前我自己写的简易循环一断就全完，因为所有历史都在内存里。Agent SDK 的会话机制解决的就是这个问题。
每次启动任务时，留意 session_event 里返回的 session_id，把它存到本地或者数据库。下次需要继续时，在 start 参数里带上这个 session_id：
const sessionId = await readLastSessionId(); for await (const event of agent.start({ prompt: "继续刚才的仓库整理任务，先报告已经完成的部分。", session_id: sessionId, })) { // 处理事件 }模型会带着之前的上下文继续干活，它能记得自己已经把临时文件归档了、正在处理文档目录，而不是从头开始一遍。如果任务特别长，还可以开启 Checkpoint 能力，SDK 会在关键节点保存会话快照，进程崩溃后可以从最近的快照恢复，而不是从零重跑。我在一个每周自动清理构建产物的任务里用了这套机制，之前偶尔会因为中途超时导致重复清理，现在中断后能续上，重复操作明显减少了。
5. 生产化改造：步数限制、权限闸门与成本控制
5.1 maxTurns 与 permissionMode：给 Agent 装上刹车
跑通 demo 之后，第一个要考虑的问题是：如果 Agent 失控了怎么办？我的一个同事把一句“清理磁盘”交给 Agent，它扫描完目录后开始递归寻找大文件，一步步往系统目录深处走，要不是设置了最大步数，它能跑出一个惊人的 token 账单。这就是为什么我在所有生产级任务里都会显式设置maxTurns。任务越危险、越开放，上限就越低。整理文件的活我一般给 40 步，代码审查类任务给 60 步，纯问答不到 10 步就够。超步数后任务会抛出一个可捕获的错误，你可以在外面决定是重试、给更多步数，还是直接放弃。
权限模式也要从一开始就考虑清楚。SDK 里有几档：默认模式遇到未授权工具会停下来等人确认，适合交互场景；计划模式只允许模型规划、不允许执行，适合先让它出方案、人看完再动手；还有直接放行的模式，适合完全可信的 CI 环境。我自己的偏好是：交互式任务保持默认，自动化任务里把所有工具白名单列全，高危操作一律靠 hooks 拦截，而不是简单粗暴地全局放行。
5.2 Hooks：在工具执行前后插入你自己的规则
Hook 是生产化改造里最实用的机制，它让你在 Agent 每次调用工具之前和之后介入控制。我最常做的两件事：拦截高危命令、强加人工审批。
下面的代码示意了一个 PreToolUse hook 的拦截逻辑：
const agent = new Agent({ // ... hooks: [ { matcher: "PreToolUse", hook: async (input) => { const command = input.tool_input.command ?? ""; if (input.tool_name === "Bash" && /rm\s+-rf/.test(command)) { return { hookSpecificOutput: { hookDecision: "block", reason: "高危删除命令已被策略拦截，请改用安全归档方式", }, }; } return { hookSpecificOutput: { hookDecision: "continue" } }; }, }, ], });这里的关键点是：被 block 后模型会收到一条拦截原因，它不会直接放弃，而是换一种不违规的方式继续尝试。比如你禁止了rm -rf，它会改用移动到临时目录再定期清理，最终目标还是达成了。Hook 不是要把 Agent 变成提线木偶，而是把它的行动路径约束在你信任的范围内。
生产环境里我还建议在 PostToolUse 阶段做审计：把每一步的工具名、参数、返回状态拼成结构化日志，存起来。出了问题能回溯整个决策链，用户质疑时有据可查，模型优化时也有真实数据可以看。这套日志我做下来发现远比想象中有价值。
5.3 并发、限流与成本观测
Agent SDK 每个 Agent 实例管理自己的会话，多个任务可以并行跑。但并行不是免费的：每个任务都在消耗 API 配额，你本地跑 10 个整理任务，等于瞬间发出去 10 路的请求。遇到 429 限流或者超时，不要裸奔式重试，我用的是指数退避：第一次等 2 秒，第二次 4 秒，第三次 8 秒，配合最大重试次数。暴力重试只会让限流来得更快。
成本观测是很多人忽略的大问题。一个多步 Agent 任务看起来只处理一个小需求，实际 token 消耗可能是普通问答的几十倍。我在接入生产之前，特意写了个汇总逻辑，把每个事件里的 usage 数据累加起来：
let inputTokens = 0; let outputTokens = 0; for await (const event of agent.start({ prompt })) { if (event.type === "message_event") { const usage = event.event.usage; inputTokens += usage.input_tokens ?? 0; outputTokens += usage.output_tokens ?? 0; } } console.log(`input: ${inputTokens}, output: ${outputTokens}`);有了这个数据，你才能判断某个任务是不是“成本黑洞”。我见过一个看似简单的文档整理任务，因为工具描述不清晰，模型反复读大文件、反复确认，最后 token 消耗是正常值的 8 倍。成本问题本质上是设计问题：工具描述越清楚、返回值越精简、约束越明确，模型的无效尝试就越少，账单自然可控。
6. 踩坑记录与“该不该用 Agent”的判断标准
6.1 我在实际项目里踩过的三个坑
第一个坑是提示词写得像“客服”。我给一个内部工具写的系统提示是“你是一个友好助手，乐于帮助用户解决问题”，结果模型在任务里特别啰嗦，每做一步都要解释一遍。后来改成“你是任务执行器，完成目标后只输出结果清单，不要额外说明动机”，整个任务立刻利落很多。记住：Agent 不是陪聊，提示词里应该写清楚任务的完成标准、输出格式和终止条件。
第二个坑是工具描述里的“承诺”太满。我给查询服务写的描述是“返回订单所有信息”，结果模型以为一次调用就能拿到物流、金额、发票全部内容，实际上我的接口只能返回基础状态。模型只能按照描述去理解工具能力，所以描述必须写清楚边界：“仅返回 CSV 文件列表，不返回内容；如需要读取内容请使用另一个工具”。边界写清楚，模型就不会产生不切实际的预期。
第三个坑是我之前提过的重试问题。有一次 Agent 在调用一个偶发超时的工具时，连续重试了五次，每次都把同样的参数原样传进去。后来我在工具描述里加了“如果连续两次失败，直接向用户报告，不要自动重试”，同时在 PostToolUse hook 里统计了同一工具连续失败次数，超过阈值直接中断。两层防护之后，这个问题才真正解决。
6.2 适合 Agent 的任务和不该交给它的任务
用了大半年之后，我对“什么活适合 Agent”的判断标准越来越简单：目标明确、过程开放、验证容易。整理文件、代码审查、跑测试并修问题、抓日志定位故障，这类任务都合适，因为结果是否达成很容易验证，路径让模型自己探索反而效率更高。
反过来，目标模糊、结果不可验证、涉及重大责任的场景，我坚决不碰。比如涉及财务对账的任务，哪怕模型最后给出了和人工一样的数字，我也不愿意为中间任何一步的不确定性负责；还有需要大量主观判断的创意工作，模型容易“过度发挥”，反而需要人来反复返工。另一个雷区是“持续实时决策”，比如在线交易系统的自动监控，Agent 的循环节奏是几百毫秒到几秒一次，不适合毫秒级响应场景。下面是适合与不适合的任务对照，我接到需求时都会先过一遍这张表：
| 适合交给 Agent | 不适合交给 Agent |
|---|---|
| 仓库、文档、日志清理 | 财务对账与合同审核 |
| 重复性代码修改与批量重构 | 不可逆的高风险写入操作 |
| 故障排查与数据采集 | 需要实时毫秒级响应的控制逻辑 |
| 测试执行与结果汇总 | 高度依赖人类直觉与主观审美的产出 |
| 定期的数据处理流水线 | 法律法规相关的决策性输出 |
如果我不确定，就让 Agent 先跑一个“只读版本”，只观察、只规划、不执行，把方案先交上来。这个习惯帮我挡住了不少本来会造成事故的任务。我第一次在团队里推广 Agent 方案时，定的规矩也是头两周全部走只读模式，跑顺了再逐步放开写权限。现在回想起来，这个渐进路径比一上来就上生产任务稳妥得多。你第一次跑自己的 Agent 任务时，也建议遵循同样的节奏：先让它观察，再让它建议，最后才让它动手。
