Claude Agent SDK：可靠 Agent 的核心是上下文—行动—验证循环

Claude Agent SDK 的关键不是给模型再包一层 API，而是给它一台可操作的计算机，并围绕“收集上下文—采取行动—验证结果—继续迭代”构建完整 Agent 循环。

1. 原文说了什么

给 Agent 一台计算机

Claude Code 最初服务于编程，但它的底层 harness 后来被用于研究、视频制作和笔记等非编码任务。Anthropic 因而把 Claude Code SDK 更名为 Claude Agent SDK，强调这套循环可以支撑通用 Agent。

核心设计原则是让模型拥有与人类工作者相近的数字工具：读取和编辑文件、运行终端命令、搜索、生成代码、检查结果并反复修正。金融助理、个人助理、客服和深度研究只是这种通用工作环境的不同配置。

第一步：收集上下文

Agent 不应只接收一次性 Prompt，而应能主动寻找和更新上下文。原文给出几种机制：

• 文件系统与 Agentic Search：大文件留在外部，Agent 用搜索、筛选和局部读取寻找相关内容。
• 语义搜索：速度通常更快，但维护成本、透明度和精确性可能更差；Anthropic 建议先从 Agentic Search 开始，确有需要再加向量检索。
• Subagents：既可并行处理不同查询，也能隔离上下文，只把相关结果返回主 Agent。
• Compaction：长期任务接近上下文上限时，对历史消息做摘要，延长循环寿命。

第二步：采取行动

工具是 Agent 最显眼的行动入口，因此工具设计会直接影响模型的选择。原文把行动能力分为几个层次：

• 业务工具承担高频、明确的主要动作。
• Bash 提供通用计算机操作能力。
• 代码生成适合精确、可组合和可复用的复杂处理。
• MCP 提供 Slack、GitHub、Google Drive、Asana 等标准化外部连接。

这里的关键不是工具越多越好，而是让每种工具拥有清楚的职责，让 Agent 能在上下文中识别“现在应该采取哪个动作”。

第三步：验证结果

Anthropic 把验证视为 Agent 循环不可缺少的一段。原文给出三类反馈：

1. 规则反馈：类型检查、lint、字段校验等确定性规则，失败时提供具体原因。
2. 视觉反馈：对 UI、HTML 邮件或其他视觉输出截图，再让模型检查布局、样式和层级。
3. LLM 评审：用另一个模型按模糊标准判断语气或质量，但稳定性与延迟都不如确定性检查。

当 Agent 反复失败时，应追问它缺的是信息、规则还是工具，并把真实客户任务沉淀为代表性评估集。

2. 我是怎么理解的

这篇文章实际上给出了一个 Agent harness 的最小结构：

外部状态 → 主动检索 → 工具或代码执行 → 可观测反馈 → 修正 → 再执行

模型只是循环中的决策器。文件系统负责承载长寿命状态，工具负责改变世界，验证器负责把环境结果重新编码成模型可理解的反馈。没有后两段，所谓 Agent 只是会调用 API 的聊天模型。

Subagent 的价值也不只是模拟岗位。更本质的用途是上下文隔离：让多个工作单元分别浏览大量材料，再把压缩后的相关结果交给主循环。它应该由任务的可并行性和信息边界驱动，而不是由组织结构图驱动。

3. 我的判断是什么

我认同先使用文件系统和直接搜索，再决定是否引入向量检索。这能保留可观察的搜索路径，也减少过早建设复杂索引的成本。

我也认同“验证能力决定 Agent 上限”。不过，“给 Agent 一台计算机”同时扩大了风险面。终端、代码执行和 MCP 都可能访问真实数据或产生外部副作用，因此生产系统还需要原文没有展开的工程护栏：

• 最小权限与明确的允许列表
• 隔离工作目录和沙盒
• 对外部写操作的人工确认
• 幂等设计与可回滚操作
• 完整的工具调用与产物审计

此外，Compaction 会丢失细节，LLM 评审会带来偏差。它们适合作为辅助机制，不能替代结构化状态和确定性规则。

4. 可以怎么使用

设计一个新 Agent 时，可以按以下顺序落地：

1. 写出循环结束条件：什么结果才算任务完成。
2. 列出完成任务必须读取的状态，优先放在可搜索文件或明确 API 中。
3. 只暴露少量主要动作；通用 Bash 和代码执行放在受控环境。
4. 为每类动作定义反馈：退出码、结构化结果、截图、测试或人工确认。
5. 先接确定性验证，再在无法形式化的部分加入 LLM 评审。
6. 只有当主 Agent 的上下文被大量无关资料挤占，或任务确实可并行时，再引入 Subagents。
7. 从真实失败构建评估集，持续判断问题来自检索、工具、规则还是权限。

一个可靠 Agent 的验收问题不是“它能不能调用工具”，而是“它能否发现自己做错，并在安全边界内修正”。