本文翻译自 Anthropic 官方博客：Building agents with the Claude Agent SDK
译者注：本文是 Anthropic Agent 开发最佳实践系列的第二篇，介绍了使用 Claude Agent SDK 的实战方法。
去年，我们与客户分享了构建高效代理的经验教训。自那时起，我们发布了 Claude Code，这是一个最初为支持 Anthropic 开发者生产力而构建的代理编码解决方案。
在过去几个月中，Claude Code 远远超出了编码工具的范畴。在 Anthropic，我们已将其用于深度研究、视频创作和笔记记录，以及无数其他非编码应用。事实上，它已经开始为几乎所有我们的主要代理循环提供动力。
换句话说，为 Claude Code 提供动力的代理框架（Claude Code SDK）也可以为许多其他类型的代理提供动力。为了反映这一更广泛的愿景，我们将 Claude Code SDK 重命名为 Claude Agent SDK。
在本文中，我们将重点介绍为什么要构建 Claude Agent SDK，如何使用它构建你自己的代理，并分享我们团队自己部署中涌现的最佳实践。
给 Claude 一台计算机
Claude Code 背后的关键设计原则是，Claude 需要程序员每天使用的相同工具。它需要能够在代码库中找到适当的文件，编写和编辑文件，检查代码，运行它，调试，编辑，有时迭代执行这些操作直到代码成功。
我们发现，通过让 Claude 访问用户的计算机（通过终端），它拥有了像程序员一样编写代码所需的一切。
但这也使 Claude Code 中的 Claude 在非编码任务中变得有效。通过给予它运行 bash 命令、编辑文件、创建文件和搜索文件的工具，Claude 可以读取 CSV 文件，搜索网络，构建可视化，解释指标，并执行所有其他类型的数字工作——简而言之，创建具有计算机的通用代理。Claude Agent SDK 背后的关键设计原则是给你的代理一台计算机，让它们像人类一样工作。
创建新类型的代理
我们相信，给 Claude 一台计算机解锁了构建比以前更有效的代理的能力。例如，使用我们的 SDK，开发者可以构建：
- 金融代理：构建能够理解你的投资组合和目标的代理，以及通过访问外部 API、存储数据和运行代码进行计算来帮助你评估投资。
- 个人助理代理：构建能够帮助你预订旅行和管理日历的代理，以及通过连接到你的内部数据源并在应用程序之间跟踪上下文来安排约会、整理简报等。
- 客户支持代理：构建能够处理高模糊度用户请求（如客户服务票据）的代理，通过收集和审查用户数据、连接到外部 API、向用户回复消息以及在需要时升级给人类。
- 深度研究代理：构建能够通过搜索文件系统、分析和综合来自多个来源的信息、交叉引用文件中的数据以及生成详细报告，在大文档集合中进行全面研究的代理。
以及更多。从根本上说，SDK 为你提供了原语，可以为你试图自动化的任何工作流构建代理。
构建你的代理循环
在 Claude Code 中，Claude 通常在特定的反馈循环中运行：收集上下文 -> 采取行动 -> 验证工作 -> 重复。
代理通常在特定的反馈循环中运行：收集上下文 -> 采取行动 -> 验证工作 -> 重复。
这为思考其他代理以及它们应该被赋予的能力提供了一种有用的方式。为了说明这一点，我们将通过如何在 Claude Agent SDK 中构建邮件代理的示例来进行说明。
收集上下文
在开发代理时，你想给它的不只是一个提示：它需要能够获取和更新自己的上下文。以下是 SDK 中的功能如何提供帮助。
代理搜索和文件系统
文件系统代表可以被拉入模型上下文的信息。
当 Claude 遇到大文件（如日志或用户上传的文件）时，它将通过使用 grep 和 tail 等 bash 脚本来决定将这些加载到其上下文中的方式。本质上，代理的文件夹和文件结构成为一种上下文工程形式。
我们的邮件代理可能会将以前的对话存储在名为"Conversations"的文件夹中。这将允许它在被问及这些对话时搜索它们以获取其上下文。
语义搜索
语义搜索通常比代理搜索更快，但准确性较低，更难维护，透明度也较低。它涉及将相关上下文"分块"，将这些块嵌入为向量，然后通过查询这些向量来搜索概念。鉴于其局限性，我们建议从代理搜索开始，只有在需要更快的结果或更多变化时才添加语义搜索。
子代理
Claude Agent SDK 默认支持子代理。子代理主要有两个原因。首先，它们实现并行化：你可以启动多个子代理同时处理不同的任务。其次，它们帮助管理上下文：子代理使用自己独立的上下文窗口，只向编排器发送相关信息，而不是它们的完整上下文。这使它们成为需要筛选大量信息且其中大部分信息不会有用的任务的理想选择。
在设计邮件代理时，我们可能会给它"搜索子代理"能力。然后，邮件代理可以并行启动多个搜索子代理——每个对邮件历史运行不同的查询——并让它们只返回相关摘录而不是完整的邮件线程。
压缩
当代理长时间运行时，上下文维护变得至关重要。Claude Agent SDK 的压缩功能会在上下文限制接近时自动汇总以前的消息，因此你的代理不会用完上下文。这是基于 Claude Code 的压缩斜杠命令构建的。
采取行动
一旦你收集了上下文，你就会想给代理灵活的采取行动的方式。
工具
工具是代理执行的主要构建块。工具在 Claude 的上下文窗口中很突出，使它们成为 Claude 在决定如何完成任务时考虑的主要行动。这意味着你应该有意识地设计你的工具以最大化上下文效率。你可以在我们的博客文章"Writing effective tools for agents – with agents"中看到更多最佳实践。
因此，你的工具应该是你希望代理采取的主要行动。了解如何在 Claude Agent SDK 中制作自定义工具。
对于我们的邮件代理，我们可能会将诸如"fetchInbox"或"searchEmails"之类的工具定义为代理的主要、最常见的行动。
Bash 和脚本
Bash 作为通用工具很有用，允许代理使用计算机进行灵活的工作。
在我们的邮件代理中，用户可能在附件中存储重要信息。Claude 可以编写代码下载 PDF，将其转换为文本，并通过调用对其进行搜索以找到有用信息，如下图所示：
代码生成
Claude Agent SDK 擅长代码生成——这是有充分理由的。代码精确、可组合且无限可重用，使其成为需要可靠执行复杂操作的代理的理想输出。
在构建代理时，请考虑：哪些任务会受益于被表达为代码？通常，答案会解锁重大能力。
例如，我们最近在 Claude.AI 中推出的文件创建完全依赖于代码生成。Claude 编写 Python 脚本来创建 Excel 电子表格、PowerPoint 演示文稿和 Word 文档，确保一致的格式和复杂的功能，而这些很难通过其他方式实现。
在我们的邮件代理中，我们可能希望允许用户为入站邮件创建规则。为此，我们可以编写代码在该事件上运行：
MCP
模型上下文协议（MCP）提供到外部服务的标准化集成，自动处理身份验证和 API 调用。这意味着你可以将代理连接到 Slack、GitHub、Google Drive 或 Asana 等工具，而无需编写自定义集成代码或自己管理 OAuth 流程。
对于我们的邮件代理，我们可能想要搜索 Slack 消息以了解团队上下文，或检查 Asana 任务以查看是否已经分配了某人处理客户请求。使用 MCP 服务器，这些集成开箱即用——你的代理可以简单地调用诸如 search_slack_messages 或 get_asana_tasks 之类的工具，MCP 处理其余的事情。
不断增长的 MCP 生态系统意味着你可以随着预构建集成的可用性快速为代理添加新功能，让你专注于代理行为。
验证你的工作
Claude Code SDK 通过评估其工作来完成代理循环。能够检查和改进自己输出的代理从根本上更可靠——它们在错误复合之前捕捉错误，在漂移时自我纠正，并在迭代时变得更好。
关键是给 Claude 提供具体的方法来评估其工作。以下是我们发现有效的三种方法：
定义规则
最好的反馈形式是为输出提供明确定义的规则，然后解释哪些规则失败以及为什么。
代码检查是基于规则的反馈的绝佳形式。反馈越深入越好。例如，生成 TypeScript 并对其进行检查通常比生成纯 JavaScript 更好，因为它为你提供了额外的反馈层。
在生成电子邮件时，你可能希望 Claude 检查电子邮件地址是否有效（如果无效，则抛出错误），以及用户以前是否向其发送过电子邮件（如果是，则抛出警告）。
视觉反馈
当使用代理完成视觉任务（如 UI 生成或测试）时，视觉反馈（以屏幕截图或渲染的形式）可能会有所帮助。例如，如果发送带有 HTML 格式的电子邮件，你可以截取生成的电子邮件的屏幕截图，并将其提供回模型以进行视觉验证和迭代优化。然后，模型将检查视觉输出是否与请求的内容匹配。
例如：
- 布局 - 元素是否正确定位？间距是否合适？
- 样式 - 颜色、字体和格式是否按预期显示？
- 内容层次结构 - 信息是否以正确的顺序呈现并具有适当的强调？
- 响应性 - 是否看起来破碎或拥挤？（尽管单个屏幕截图的视口信息有限）
使用像 Playwright 这样的 MCP 服务器，你可以自动化这个视觉反馈循环——获取渲染 HTML 的屏幕截图，捕获不同的视口大小，甚至测试交互元素——所有这些都在代理的工作流中。
来自大型语言模型（LLM）的视觉反馈可以为代理提供有用的指导。
LLM 作为评判
你还可以让另一个语言模型根据模糊规则"评判"你的代理的输出。这通常不是一种非常稳健的方法，并且可能具有沉重的延迟权衡，但对于任何性能提升都值得成本的应用程序，它可能会有所帮助。
我们的邮件代理可能有一个单独的子代理来评判其草稿的语气，以查看它们是否与用户以前的消息很好地匹配。
测试和改进你的代理
在完成代理循环几次后，我们建议你测试代理，并确保其任务配备良好。改进代理的最好方法是仔细查看其输出，特别是失败的情况，并设身处地：它是否有正确的工具来完成工作？
在评估代理是否配备良好的工作时，还有其他一些问题要问：
- 如果你的代理误解了任务，它可能缺少关键信息。你能更改搜索 API 的结构以便更容易找到它需要知道的内容吗？
- 如果你的代理反复失败于某项任务，你可以在工具调用中添加正式规则来识别和修复失败吗？
- 如果你的代理无法修复其错误，你能给它更有用或更有创意的工具以不同方式解决问题吗？
- 如果你的代理的性能在添加功能时发生变化，请根据客户使用情况构建代表性测试集以进行程序化评估（或评估）。
入门
Claude Agent SDK 通过让 Claude 访问可以写文件、运行命令并迭代其工作的计算机，使构建自主代理变得更容易。
考虑到代理循环（收集上下文、采取行动和验证工作），你可以构建易于部署和迭代的可靠代理。
你今天就可以开始使用 Claude Agent SDK。对于已经在 SDK 上构建的开发者，我们建议按照此指南迁移到最新版本。
致谢
由 Thariq Shihipar 撰写，Molly Vorwerck、Suzanne Wang、Alex Isken、Cat Wu、Keir Bradwell、Alexander Bricken 和 Ashwin Bhat 提供注释和编辑。