Claude Agent SDK 的核心不是工具，而是可验证的工作闭环
让模型搜索邮件、读取附件、运行脚本，并不难。真正难的是：它找到的文件是不是对的，算出的金额有没有错，生成的邮件能不能直接发送；一旦中间某一步失败，它又是否知道该回到哪里重来。
这正是 Anthropic 在《Building agents with the Claude Agent SDK》里想讲清楚的事。Claude Agent SDK 的核心并不是"再给模型接几个 API"，而是把电脑变成一个可操作、会反馈的工作环境，让 Claude 能够不断经历：获取上下文、采取行动、验证结果，然后根据反馈决定下一步。
换句话说，工具只解决"能不能做"；闭环才决定 Agent 能不能把一件事真正做完。
本文是对 Anthropic 官方文章 Building agents with the Claude Agent SDK 的解读，重点分析"给 Agent 一台电脑"背后的设计逻辑，以及为什么验证能力决定了 Agent 能否真正完成工作。
一个会调用工具的模型，为什么还不等于 Agent
先看官方文章使用的邮件 Agent 场景。
用户提出一个目标：找到某封邮件中的报价附件，比较新旧报价，再起草回复。表面上，这只是一次问答；真正执行时，路径却无法提前完全写死：
- 搜索结果可能有多封同名邮件；
- 附件可能是 PDF，也可能是表格；
- 旧报价不在当前会话里，需要继续查找；
- 金额计算完成后，还要检查币种、地址和邮件格式；
- 检查失败后，不能直接结束，而要带着错误重新行动。
固定工作流擅长执行已经写好的步骤，但这个任务的下一步取决于刚刚拿到的结果。模型的作用，是在每一轮重新判断"现在缺什么、该做什么"；SDK 的作用，则是执行工具、把结果送回模型，并维持这个循环。
因此，Agent 与"接了工具的聊天机器人"之间真正的分界，不是工具数量，而是工具结果能否成为下一轮决策的依据。
"给 Claude 一台电脑"，重点不是电脑，而是统一的工作环境
Anthropic 把 Claude Code 的关键设计原则概括为：给 Claude 程序员每天使用的工具，让它能搜索文件、修改代码、运行程序、调试，再根据结果继续修改。
后来他们发现，这套设计并不只适用于写代码。终端、文件系统和脚本本来就是通用的数字工作环境：CSV 可以被读取，日志可以被搜索，数据可以被计算，页面可以被渲染，文档可以被生成。编程只是其中一种任务。
这也是 Claude Code SDK 更名为 Claude Agent SDK 的逻辑：被抽象出来的不是某个"代码生成能力"，而是一套能支撑多种 Agent 的运行方式。
这里的"电脑"可以拆成三类能力：
- 文件系统承载候选信息：资料不必一次全部塞进上下文，Agent 可以按需搜索和读取；
- 终端与代码承载通用行动：当没有现成工具时，Agent 仍能用脚本组合出新的处理路径；
- 工具与 MCP 连接外部系统：邮件、Slack、GitHub、Asana 等服务可以成为工作环境的一部分。
三类能力共同带来的变化是：Claude 不再只能根据一段静态输入生成答案，而是可以读取外部状态、改变外部状态，再观察改变后的结果。
真正的产品骨架，是一个不断接收反馈的循环
官方文章用三个动作概括 Agent 的工作方式：
这张图最重要的不是三个方框，而是从"验证"返回"获取上下文"的那条边。没有它，系统仍然只是一次性的生成器；有了它，错误才可能变成下一轮行动的输入。
以邮件 Agent 为例，这个循环会这样展开：
- 搜索相关邮件，读取正文和附件，这是获取上下文；
- 下载文件、解析报价、运行计算脚本，这是采取行动；
- 检查邮箱地址、金额和渲染效果，这是验证结果；
- 如果金额对不上，就回到附件和计算过程继续查，而不是带着错误生成最终邮件。
所以，设计 Agent 时最有效的问题不是"还可以给它加什么工具"，而是依次检查：它做决定前看得到什么？它能改变什么？环境又怎样明确告诉它做对了没有？
上下文工程不是把资料塞满，而是让 Agent 找到此刻需要的部分
官方文章有一个很值得保留的判断：文件系统代表的是可能进入上下文的信息，而不是模型已经看到的信息。
这一区别改变了 Agent 的知识组织方式。面对一份很长的日志，Agent 不必先读取全部内容；它可以用 grep、tail 或脚本定位相关片段，再把少量高信号信息送进当前上下文。文件夹结构、文件命名和搜索方式，也因此成了上下文工程的一部分。
Anthropic 建议先从这种 Agent 自主搜索开始，而不是一开始就建设语义搜索。语义搜索通常更快，也能找到不同措辞表达的相近概念，但它还带来分块、向量索引、维护成本和结果不透明等问题。对于结构清楚的文件、代码和日志，文本搜索往往已经足够直接。
当资料规模继续增大，官方文章给出了两种不同的减压方式：
- 子 Agent把独立搜索放进各自的上下文中，可以并行工作，最后只把相关结果交回主 Agent；
- 上下文压缩在窗口接近上限时总结较早的消息，为后续行动腾出空间。
它们解决的都不是"让模型记住一切"，而是让有限的上下文始终保留当前决策最需要的信息。
工具的价值不在数量，而在于是否成为 Agent 的自然动作
工具定义会直接出现在 Claude 的上下文里，也会影响它对下一步行动的判断。由此会得到一个不太直观的结论：工具不是越多越好。
如果工具名称含糊、职责重叠，或者每次返回大量无关内容，Agent 就会把有限的上下文花在辨认工具和清理结果上。官方文章因此强调，工具应该对应 Agent 最主要、最常见的动作。对邮件 Agent 来说，fetchInbox、searchEmails 这样的能力，比一组边界模糊的底层接口更容易被正确使用。
但专用工具不可能覆盖所有情况，这就是 Bash 和代码生成重要的原因。
代码是一种精确、可组合、可复用的行动表达。遇到 PDF 附件，Agent 可以临时编写脚本完成下载、转文本和搜索；遇到需要重复执行的邮件规则，它可以把这套规则写成程序。关键不在于"Claude 会写代码"，而在于代码可以运行，运行结果又能继续接受检查。
MCP 则解决另一层问题：用统一方式把外部服务接入 Agent。它扩展了 Agent 能触及的系统，但不会替 Agent 决定何时调用，也不会自动补上结果验证。连接能力只是闭环的一段，不是闭环本身。
Agent 是否可靠，分水岭在验证，不在生成
很多 Agent 演示会把注意力放在"它完成了多少步"，但官方文章把最后一段留给了验证，而且明确指出：能检查并改进自身输出的 Agent，才更可靠。
文章给出的反馈方式可以按判断对象来理解：
- 明确规则适合可以程序化判断的问题。例如邮箱格式是否合法、计算结果是否一致、代码能否通过类型检查；
- 视觉反馈适合源码无法完整反映的问题。例如 HTML 邮件是否溢出、层级是否清楚、移动端是否拥挤；
- LLM 评审适合语气、风格等模糊标准，但稳定性较弱，还会增加延迟，因此更适合作为补充。
这三种方式的共同点，是把"感觉应该完成了"变成环境中可观察的反馈。
只让 Claude 自己阅读刚生成的答案，再问一句"你确定吗"，并没有建立强验证。有效反馈必须尽量指向具体失败：哪个测试没过、哪项金额不一致、哪个页面状态出现异常。反馈越具体，下一轮行动越有方向。
改进 Agent，不要先换模型，先观察它在哪里失去闭环
官方文章最后给出的优化思路非常务实：仔细看失败输出，再反推 Agent 缺少什么。
如果 Agent 经常误解任务，问题可能不在推理能力，而在它拿不到关键上下文；如果它反复调用错工具，可能是工具定义和边界不清楚；如果它知道结果有错却修不好，可能缺少新的行动路径；如果增加功能后表现开始波动，就需要用贴近真实使用的测试集持续评估。
这套排查方式可以压缩成一张表：
| 失败发生在哪里 | 优先检查什么 |
|---|---|
| 找不到或误解信息 | 文件组织、搜索入口、返回内容是否高信号 |
| 不知道该调用什么 | 工具名称、职责边界、参数说明 |
| 做了但不知道对不对 | 是否存在规则、测试、截图或其他可观察反馈 |
| 知道错了却无法修正 | 是否有替代工具或可执行的新路径 |
| 偶尔成功、整体不稳定 | 是否建立了覆盖真实任务的评估集 |
这比笼统地归因于"模型不够聪明"更有操作价值。Agent 的表现来自整个系统：模型只是决策者，信息入口、行动能力和反馈机制共同决定它能走多远。
这篇官方文章解释了能力骨架，但不是完整的生产指南
这篇文章最有价值的地方，是给出了一套非常清楚的 Agent 设计骨架；它没有试图穷尽生产环境中的所有问题。
当 Agent 真正能够读取文件、执行命令和连接外部服务后，开发者仍然需要继续回答权限、隔离、成本、超时、失败恢复和人工审批等问题。尤其是发送邮件、修改数据等不可轻易撤销的动作，不能因为 Agent 已经完成自我检查，就默认允许自动执行。
这不是对文章结论的否定，反而说明了"给 Agent 一台电脑"的准确边界：电脑提供行动空间，反馈循环提供改进能力，但系统设计者仍要决定它能走到哪里、什么结果才算通过。
最后真正该记住的，是三张设计清单
Claude Agent SDK 把 Claude Code 背后的运行方式开放给了更多场景。它最值得借鉴的，不是某个具体工具，而是下面三组问题：
- 上下文：Agent 做下一步决定前，能否找到真正相关的信息？
- 行动：它是否拥有完成任务所需、边界清楚的操作方式？
- 验证：环境能否用足够具体的信号告诉它哪里做错，并让反馈进入下一轮？
如果第三个问题没有答案，前两个问题做得越强，Agent 也可能只是更快地产生一个未经验证的结果。
因此，读完这篇官方文章后最值得带走的判断是：**不要从工具列表开始设计 Agent，要从一个可验证的工作闭环开始。**工具决定它可以做什么，反馈决定它最终能不能把事情做对。