🤖 使用 Claude Agent SDK 构建 Agent

原文：Building agents with the Claude Agent SDK

去年，我们与客户分享了构建高效 Agent 的经验教训。此后，我们发布了 Claude Code，这是一个 Agent 化的编程解决方案，最初是为了提高 Anthropic 内部的开发者生产力而构建的。

在过去的几个月里，Claude Code 已经成为一个远不止编程工具的存在。在 Anthropic，我们用它来进行深度研究、视频创作、记笔记，以及无数其他非编程任务。事实上，它已经开始为几乎所有主要的 Agent 循环提供动力。

换句话说，为 Claude Code 提供动力的 Agent 框架（Claude Code SDK）也可以为许多其他类型的 Agent 提供动力。为了反映这一更广阔的愿景，我们将 Claude Code SDK 更名为 Claude Agent SDK。

在这篇文章中，我们将重点介绍我们为什么构建 Claude Agent SDK、如何使用它构建你自己的 Agent，以及分享我们团队在部署过程中总结的最佳实践。

🎯 给 Claude 一台计算机

关键设计原则是：Claude 需要与程序员每天使用的工具相同。它需要能够在代码库中找到合适的文件、编写和编辑文件、lint 代码、运行代码、调试、修改，有时还需要重复这些操作直到代码成功。

我们发现，通过让 Claude 访问用户的计算机（通过终端），它就拥有了像程序员一样编写代码所需的一切。

但这也使得 Claude Code 中的 Claude 在非编程任务中同样有效。通过赋予它运行 bash 命令、编辑文件、创建文件和搜索文件的能力，Claude 可以读取 CSV 文件、搜索网络、构建可视化图表、解读指标，以及完成各种其他数字工作——简而言之，创建通用目的的计算机 Agent。Claude Agent SDK 的关键设计原则就是给你的 Agent 一台计算机，让它们像人类一样工作。

🧩 创建新型 Agent

我们相信，给 Claude 一台计算机能够解锁构建比以往更有效的 Agent 的能力。例如，使用我们的 SDK，开发者可以构建：

• 金融 Agent：构建能够理解你的投资组合和目标、通过访问外部 API、存储数据和运行代码进行计算来帮助你评估投资的 Agent。
• 个人助理 Agent：构建能够帮助你预订旅行和管理日历、安排预约、整理简报，并通过连接到你的内部数据源和在应用程序间跟踪上下文来为你做更多的 Agent。
• 客户支持 Agent：构建能够处理高模糊度用户请求（如客服工单）的 Agent，通过收集和审查用户数据、连接到外部 API、回复用户消息并在需要时升级给人工客服。
• 深度研究 Agent：构建能够跨大型文档集合进行全面研究的 Agent，通过搜索文件系统、分析和综合来自多个来源的信息、跨文件交叉引用数据，并生成详细报告。

还有更多。Core 上来讲，这个 SDK 为你提供了为任何你想要自动化的 工作流构建 Agent 的基本原语（primitives）。

🔄 构建你的 Agent 循环

在 Claude Code 中，Claude 通常以特定的反馈循环运行：收集上下文 → 采取行动 → 验证工作 → 重复。

Agent 通常以特定的反馈循环运行：收集上下文 → 采取行动 → 验证工作 → 重复。这为思考其他 Agent 及其应该具备的能力提供了一种有用的方式。为了说明这一点，我们将详细介绍如何使用 Claude Agent SDK 构建一个电子邮件 Agent。

📥 收集上下文

在开发 Agent 时，你希望给它不仅仅是提示词：它需要能够获取和更新自己的上下文。以下是 SDK 中可以帮助实现这一点的功能。

Agentic Search 和文件系统

文件系统代表可以被拉入模型上下文中信息。

当 Claude 遇到大型文件（如日志或用户上传的文件）时，它会决定使用哪种方式将这些加载到上下文中，比如使用 grep 和 tail 等 bash 脚本。从本质上讲，Agent 的文件夹和文件结构成为一种上下文工程（context engineering）形式。

我们的电子邮件 Agent 可能会将之前的对话存储在一个名为 'Conversations' 的文件夹中。这将允许它在被问到这些对话时搜索之前的对话来获取上下文。

语义搜索（Semantic Search）

语义搜索通常比 Agentic Search 更快，但不那么准确，更难维护，也不够透明。它涉及将相关上下文"分块"、将这些块嵌入为向量，然后通过查询这些向量来搜索概念。考虑到其局限性，我们建议从 Agentic Search 开始，只在需要更快结果或更多变体时才添加语义搜索。

子 Agent（Subagents）

Claude Agent SDK 默认支持子 Agent。子 Agent 主要有两个用途。首先，它们支持并行化：你可以启动多个子 Agent 同时处理不同的任务。其次，它们帮助管理上下文：子 Agent 使用自己独立的上下文窗口，只向编排器发送相关信息，而不是它们的完整上下文。这使得它们非常适合需要筛选大量信息的任务，其中大部分信息不会有帮助。

在设计我们的电子邮件 Agent 时，我们可能会赋予它一个"搜索子 Agent"能力。然后，电子邮件 Agent 可以并行分支出多个搜索子 Agent——每个对你的邮件历史运行不同的查询——并让它们只返回相关摘录而不是完整的邮件线程。

压缩（Compaction）

当 Agent 长时间运行时，上下文维护变得至关重要。Claude Agent SDK 的 compact 功能会在接近上下文限制时自动总结之前的消息，这样你的 Agent 就不会耗尽上下文。这是基于 Claude Code 的 compact 斜杠命令构建的。

⚡ 采取行动

一旦你收集了上下文，你将希望给你的 Agent 灵活的行动方式。

工具（Tools）

工具是 Agent 执行的主要构建块。工具在 Claude 的上下文中非常突出，使得它们成为 Claude 在决定如何完成任务时考虑的主要行动。这意味着你应该有意识地设计你的工具，以最大化上下文效率。你可以在我们的博客文章《为 Agent 编写有效的工具》中看到更多最佳实践。

因此，你的工具应该你想要 Agent 采取的主要行动。了解如何在 Claude Agent SDK 中制作自定义工具。

对于我们的电子邮件 Agent，我们可能会定义像 "fetchInbox" 或 "searchEmails" 这样的工具作为 Agent 最频繁的主要行动。

Bash 和脚本

Bash 作为一种通用工具很有用，允许 Agent 使用计算机做灵活的工作。

在我们的电子邮件 Agent 中，用户可能在附件中存储了重要信息。Claude 可以编写代码来下载 PDF，将其转换为文本，并搜索它以查找有用的信息，如下图所示：

代码生成

Claude Agent SDK 擅长代码生成——这是有充分理由的。代码是精确的、可组合的、可无限重用的，使其成为需要可靠执行复杂操作的 Agent 的理想输出。

在构建 Agent 时，考虑：哪些任务会受益于用代码表达？通常，答案会解锁显著的能力。

例如，我们最近在 Claude.AI 中推出文件创建功能完全依赖于代码生成。Claude 编写 Python 脚本来创建 Excel 电子表格、PowerPoint 演示文稿和 Word 文档，确保格式一致和复杂功能，而这些用其他方式很难实现。

在我们的电子邮件 Agent 中，我们可能希望允许用户为收到的邮件创建规则。为了实现这一点，我们可以编写在该事件上运行的代码：

MCP（Model Context Protocol）

模型上下文协议（Model Context Protocol，MCP）提供标准化的外部服务集成，自动处理身份验证和 API 调用。这意味着你可以将 Agent 连接到 Slack、GitHub、Google Drive 或 Asana 等工具，而无需编写自定义集成代码或自己管理 OAuth 流程。

对于我们的电子邮件 Agent，我们可能希望搜索 Slack 消息来了解团队上下文，或检查 Asana 任务以查看是否有人已经被分配处理客户请求。通过 MCP 服务器，这些集成开箱即用——你的 Agent 只需调用 search_slack_messages 或 get_asana_tasks 这样的工具，MCP 就会处理其余部分。

不断增长的 MCP 生态系统意味着你可以在预构建集成可用时快速为 Agent 添加新能力，让你专注于 Agent 行为本身。

✅ 验证你的工作

Claude Agent SDK 通过评估其工作来完成 Agent 循环。能检查和改进自己输出的 Agent 根本上是更可靠的——它们在错误累积之前抓住错误，在偏离时自我修正，并在迭代中变得更好。

关键是要给 Claude 提供评估其工作的具体方法。以下是我们发现有效的三种方法：

定义规则

最好的反馈形式是为输出提供明确定义的规则，然后解释哪些规则失败了以及为什么。

代码 linting是一种极好的基于规则的反馈形式。反馈越深入越好。例如，生成 TypeScript 并 lint 它通常比生成纯 JavaScript 更好，因为它为你提供了多层额外的反馈。

在生成电子邮件时，你可能希望 Claude 检查电子邮件地址是否有效（如果没有，抛出错误）以及用户之前是否向他们发送过电子邮件（如果有，抛出警告）。

视觉反馈

当使用 Agent 完成视觉任务时，如 UI 生成或测试，视觉反馈（以截图或渲染的形式）可能会有所帮助。例如，如果发送带有 HTML 格式的电子邮件，你可以截取生成的电子邮件截图并将其反馈给模型进行视觉验证和迭代改进。然后模型会检查视觉输出是否符合要求。

例如：

• 布局 - 元素位置是否正确？间距是否适当？
• 样式 - 颜色、字体和格式是否符合预期？
• 内容层次 - 信息是否按正确的顺序呈现并有适当的强调？
• 响应式 - 它看起来是否破损或拥挤？（尽管单张截图信息有限）

使用像 Playwright 这样的 MCP 服务器，你可以自动化这个视觉反馈循环——截取渲染 HTML 的截图、捕获不同的视口大小，甚至测试交互元素——所有这些都在你的 Agent 工作流中完成。

LLM 作为评判者

你也可以让另一个语言模型根据模糊规则"评判"你 Agent 的输出。这通常不是一个非常稳健的方法，而且可能有很大的延迟权衡，但对于任何性能提升都值得付出代价的应用来说，它可能会有所帮助。

我们的电子邮件 Agent 可能有一个单独的子 Agent 来评判其草稿的语气，看看它们是否与用户之前的消息很好地契合。

🧪 测试和改进你的 Agent

在经历了几次 Agent 循环后，我们建议测试你的 Agent，并确保它为任务做好了充分准备。改进 Agent 的最佳方式是仔细查看它的输出，特别是失败的情况，并设身处地为它着想：它是否有正确的工具来完成工作？

在评估你的 Agent 是否配备齐全以完成工作时，还要问以下一些问题：

• 如果你的 Agent 误解了任务，它可能缺少关键信息。你能否改变搜索 API 的结构，让它更容易找到需要知道的内容？
• 如果你的 Agent 反复失败，能否在你的工具调用中添加正式规则来识别和修复失败？
• 如果你的 Agent 无法修复错误，你能否给它更有用或更有创造性的工具来不同地处理问题？
• 如果你的 Agent 的性能随着添加功能而变化，基于客户使用情况构建代表性的测试集用于程序化评估（evals）。

🚀 开始使用

Claude Agent SDK 通过给 Claude 访问计算机的能力（它可以在其中写入文件、运行命令并迭代其工作）使构建自主 Agent 变得更加容易。

记住 Agent 循环（收集上下文、采取行动、验证你的工作），你可以构建易于部署和迭代的可靠 Agent。

今天就可以开始使用 Claude Agent SDK。对于已经在 SDK 上构建的开发者，我们建议按照本指南迁移到最新版本。