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