使用 Claude Agent SDK 构建代理¶
- 原文链接：https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk [55]
- 发布时间：2025-09-29
- 作者：Thariq Shihipar
Claude Agent SDK 是一组工具，让开发者在 Claude Code 之上构建更强大的代理。本文介绍入门方式与最佳实践。[55]
去年我们在与客户共同实践中总结了《Building Effective AI Agents》的经验。此后我们发布了 Claude Code，这是最初为提升 Anthropic 内部开发效率而打造的代理式编码方案。[55]
过去几个月，Claude Code 逐渐超越“编码工具”的定位。在 Anthropic，我们用它做深度研究、视频制作、笔记整理等大量非编码工作，几乎支撑了所有主要的代理循环。[55]
换句话说，驱动 Claude Code 的代理框架（Claude Code SDK）也可以驱动其他类型的代理。为了体现这一更广阔的愿景，我们将 Claude Code SDK 更名为 Claude Agent SDK。[55]
本文将解释我们为何构建 Claude Agent SDK、如何用它构建代理，以及在实际部署中总结的最佳实践。[55]
给 Claude 一台“电脑”¶
Claude Code 的关键设计原则是：Claude 需要与程序员相同的日常工具。它必须能在代码库中找到文件、编辑/写入文件、lint、运行、调试，并根据结果反复迭代直到成功。[55]
我们发现只要让 Claude 通过终端访问用户电脑，它就能像程序员一样写代码。[55]
更重要的是，这种方式也让 Claude 在非编码任务上表现出色：借助 Bash、文件编辑、创建与搜索等工具，Claude 可以读取 CSV、搜索网页、做可视化、解读指标，完成各种数字化工作——本质上就是让代理拥有一台电脑。[55]
因此，Claude Agent SDK 的核心原则是：给代理一台电脑，让它像人类一样工作。[55]
创建新的代理类型¶
让 Claude 有“电脑”之后，就能构建更强的代理。例如你可以用 SDK 构建：[55]
- 金融代理：理解投资组合与目标，调用外部 API，存储数据并运行代码以评估投资。
- 个人助理代理：预订旅行、管理日程、安排预约、准备简报等，并能连接内部数据源、跨应用追踪上下文。
- 客服代理：处理高模糊用户请求（如客服工单），收集与审查用户数据，连接外部 API，回消息并在必要时升级给人类。
- 深度研究代理：在大量文档中搜索、分析与综合信息，跨文件交叉验证并生成报告。
以及更多场景。SDK 提供的是通用“原语”，你可以组合出任何工作流所需的代理。[55]
构建你的代理循环¶
在 Claude Code 中，Claude 往往遵循这样的反馈循环：收集上下文 → 采取行动 → 验证结果 → 重复。[55]
这也是理解其他代理的一种有用方式。下面我们用“邮件代理”的例子说明该如何设计能力。[55]
图注：代理常处在“收集上下文 → 行动 → 验证 → 重复”的反馈循环中。[55]
收集上下文¶
构建代理时，不能只给一个 prompt；它需要能获取并更新自己的上下文。SDK 的以下能力对此有帮助。[55]
Agentic search 与文件系统¶
文件系统代表了“可能进入上下文”的信息集合。当 Claude 遇到大文件（如日志或用户上传文件）时，会通过 grep、tail 等脚本决定如何加载。这使文件夹与文件结构本身成为一种上下文工程。[55]
例如邮件代理可以把历史对话存储在 Conversations 文件夹中，在被询问时自行检索并载入相关历史。[55]
语义检索¶
语义检索通常比 agentic search 更快，但准确性更低、维护更难、透明性也更差。它通过分块、向量化，再以向量相似度检索。考虑其局限，我们建议先使用 agentic search；只有在需要更快结果或更多变体时再加入语义检索。[55]
子代理¶
Claude Agent SDK 默认支持子代理。子代理有两个核心价值：
- 并行化：可同时运行多个子代理处理不同任务。
- 上下文管理：子代理使用独立上下文窗口，只把相关信息汇总给主代理，避免把全部上下文回传。
这对需要筛选大量信息的任务尤其有用。[55]
在邮件代理中，你可以加入“搜索子代理”。邮件代理可以并行派出多个搜索子代理，对邮件历史执行不同查询，然后只返回相关片段，而不是整封邮件。[55]
Compaction¶
长时间运行时，上下文维护至关重要。Claude Agent SDK 的 compact 功能会在接近上下文限制时自动总结历史消息，确保代理不会“爆窗”。它基于 Claude Code 的 /compact 命令实现。[55]
采取行动¶
收集完上下文之后，你需要给代理足够灵活的行动方式。[55]
Tools¶
工具是代理执行的核心构件。工具会突出显示在 Claude 的上下文中，是它完成任务时最主要的行动选项。因此工具设计必须关注上下文效率。[55]
可参考《Writing effective tools for agents – with agents》。同时，Claude Agent SDK 支持自定义工具。[55]
对邮件代理而言，你可以定义 fetchInbox 或 searchEmails 作为主要行动工具。[55]
Bash 与脚本¶
Bash 是通用工具，允许代理像人类一样操作电脑。邮件代理可能需要处理附件：例如下载 PDF、转成文本并搜索信息。可以通过脚本来完成，如下图所示。[55]
代码生成¶
Claude Agent SDK 很擅长生成代码——代码精确、可组合、可复用，非常适合需要可靠执行复杂操作的代理。[55]
例如我们在 Claude.AI 上推出的文件创建能力，完全依赖代码生成：Claude 编写 Python 脚本来生成 Excel、PowerPoint 与 Word 文件，保证格式一致并支持复杂功能。[55]
对邮件代理而言，若要支持用户创建邮件规则，就可以用代码在事件触发时执行逻辑。[55]
MCP¶
Model Context Protocol 提供标准化集成能力，自动处理认证与 API 调用。这样你可以把代理连接到 Slack、GitHub、Google Drive、Asana 等外部服务，而无需编写定制化集成或管理 OAuth。[55]
邮件代理可调用 search_slack_messages 或 get_asana_tasks 等工具来补充团队上下文。随着 MCP 生态 扩展，你可以快速添加新能力，专注于代理行为设计。[55]
验证你的工作¶
Claude Code SDK 通过“评估输出”完成代理循环。能检查并改进自身输出的代理更可靠：它们能在错误扩大前发现问题，纠偏并持续改进。[55]
关键在于给 Claude 具体的验证手段。以下三种方法最有效：[55]
定义规则¶
最好先明确规则，再解释哪些规则失败以及为何失败。代码 lint 是极佳的规则反馈方式，而且规则越详细越好。例如相比生成纯 JavaScript，生成 TypeScript 并 lint 往往更有价值，因为它提供更多反馈层。[55]
在邮件场景中，可以要求 Claude 检查邮箱格式是否正确（错误则报错），以及是否曾向该地址发送过邮件（如有则提示警告）。[55]
视觉反馈¶
当代理处理视觉任务（如 UI 生成或测试）时，视觉反馈（截图/渲染）非常有效。例如发送 HTML 邮件时，可以截图并交给模型进行视觉验证与迭代，检查是否符合要求。[55]
常见检查维度包括：
- 布局：元素位置是否合理？间距是否正确？
- 样式：颜色、字体、格式是否符合预期？
- 层级：信息是否按正确层级呈现？
- 响应式：在不同视口是否出现挤压或错位？
使用 Playwright 等 MCP server 可以自动化视觉反馈循环：截不同视口、测试交互元素，全部纳入代理工作流。[55]
图注：来自大语言模型的视觉反馈能够为代理提供有效指导。[55]
LLM 作为评审¶
你也可以让另一个模型基于模糊规则“评审”输出。它不够稳健、延迟更高，但在性能提升值得投入的场景中仍然有用。[55]
邮件代理可以让子代理评估草稿语气是否与用户历史风格一致。[55]
测试与改进代理¶
在跑过几轮代理循环后，应测试代理并确认其能力是否匹配任务。最好的改进方式是仔细审视输出，尤其是失败案例，并站在代理视角思考：它是否拥有完成任务的正确工具？[55]
可自问：
- 如果代理误解任务，是否缺少关键信息？能否调整搜索 API 结构，让它更容易找到所需内容？
- 如果代理反复失败，能否在工具调用中加入规则，帮助识别并修复失败？
- 如果代理无法修复错误，能否给它更有用或更具创造性的工具？
- 如果性能随功能扩展波动，能否基于真实用户使用构建代表性评测集（evals）？[55]
Getting started¶
Claude Agent SDK 通过提供“可写文件、可运行命令、可迭代工作”的电脑环境，使构建自治代理更容易。[55]
围绕代理循环（收集上下文、行动、验证）来设计，你就能构建更可靠、易部署、易迭代的代理。[55]
你可以从 Agent SDK 概览 开始；若已在使用旧版本，建议按 迁移指南 升级。[55]
致谢¶
作者 Thariq Shihipar；感谢 Molly Vorwerck、Suzanne Wang、Alex Isken、Cat Wu、Keir Bradwell、Alexander Bricken、Ashwin Bhat 的笔记与编辑支持。[55]