使用 Claude Agent SDK 构建智能体

发表于 更新于 分类于 ，

原文：Building agents with the Claude Agent SDK
日期：2025年9月29日

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 在处理非编程任务时同样高效。通过赋予它运行 bash 命令、编辑文件、创建文件和搜索文件的工具，Claude 可以读取 CSV 文件、搜索网页、构建可视化图表、解读指标，以及处理各种其他数字工作——简而言之，就是用一台电脑创建通用目的的智能体。

创建新型智能体

我们相信，给 Claude 一台电脑，能够解锁构建以往不那么有效的智能体的能力。例如，使用我们的 SDK，开发者可以构建：

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

以及更多。其核心是，该 SDK 为您提供了为任何您试图自动化的工作流程构建智能体的基础模块。

构建您的智能体循环

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

智能体通常在一个特定的反馈循环中运作：收集上下文 -> 采取行动 -> 验证工作 -> 重复。

这为思考其他智能体及其应具备的能力提供了一个有用的框架。为了说明这一点，我们将通过一个例子来演示如何使用 Claude Agent SDK 构建一个电子邮件智能体。

收集上下文

在开发智能体时，您需要给它的不仅仅是一个提示：它需要能够获取和更新自己的上下文。以下是 SDK 中的功能如何提供帮助。

智能体化搜索与文件系统

文件系统代表了那些 可以 被拉入模型上下文的信息。

当 Claude 遇到大文件时，比如日志或用户上传的文件，它会决定使用像 grep 和 tail 这样的 bash 脚本来将这些文件加载到其上下文中。本质上，智能体的文件夹和文件结构成为一种上下文工程的形式。

我们的电子邮件智能体可能会将以前的对话存储在一个名为“Conversations”的文件夹中。当被问及这些对话时，这将允许它搜索这些文件以获取上下文。

语义搜索

语义搜索 通常比智能体化搜索(agentic search)更快，但准确性较低，更难维护，且透明度不高。它涉及将相关上下文“分块”，将这些块嵌入为向量，然后通过查询这些向量来搜索概念。鉴于其局限性，我们建议从智能体化搜索开始，只有在需要更快的结果或更多变化时才添加语义搜索。

子智能体(Subagents)

Claude Agent SDK 默认支持子智能体。子智能体主要有两个用处。首先，它们支持并行化：您可以启动多个子智能体同时处理不同的任务。其次，它们有助于管理上下文：子智能体使用自己隔离的上下文窗口，并且只将相关信息发送回协调器，而不是它们的全部上下文。这使得它们非常适合需要筛选大量信息但其中大部分信息无用的任务。

在设计我们的电子邮件智能体时，我们可能会赋予它一个“搜索子智能体”的能力。然后，电子邮件智能体可以并行启动多个搜索子智能体——每个子智能体针对您的邮件历史执行不同的查询——并让它们只返回相关的摘要，而不是完整的邮件线程。

压缩

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

采取行动

一旦收集了上下文，您就需要给您的智能体提供灵活的行动方式。

工具

工具是您的智能体执行任务的主要构建模块。工具在 Claude 的上下文窗口中非常显眼，这使它们成为 Claude 在决定如何完成任务时会优先考虑的行动。这意味着您应该有意识地设计您的工具，以最大化上下文效率。

您可以在我们的博客文章为智能体编写有效的工具——借助智能体中看到更多最佳实践。

因此，您的工具应该是您希望智能体采取的主要行动。了解如何在 Claude Agent SDK 中制作自定义工具。

对于我们的电子邮件智能体，我们可能会将诸如“fetchInbox”或“searchEmails”之类的工具定义为智能体的首要、最频繁的行动。

Bash 和脚本

Bash 作为一个通用工具非常有用，它允许智能体使用电脑来完成灵活的工作。

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

代码生成

Claude Agent SDK 在代码生成方面表现出色——这是有充分理由的。代码是精确、可组合且可无限重用的，这使其成为需要可靠执行复杂操作的智能体的理想输出。

在构建智能体时，请思考：哪些任务可以通过代码表达而受益？通常，答案能解锁重要的能力。

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

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

MCPs

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

对于我们的电子邮件智能体，我们可能想要搜索 Slack 消息以了解团队上下文，或检查 Asana 任务以查看是否已有人被指派处理客户请求。有了 MCP 服务器，这些集成开箱即用——您的智能体只需调用像 search_slack_messages 或 get_asana_tasks 这样的工具，MCP 会处理剩下的事情。

不断增长的 MCP 生态系统意味着您可以随着预构建集成的出现，快速为您的智能体添加新功能，让您专注于智能体的行为本身。

验证您的工作

Claude Code SDK 通过评估其工作来完成智能体循环。能够检查和改进自己输出的智能体从根本上说更可靠——它们在错误累积之前就发现错误，在偏离轨道时自我纠正，并在迭代中变得更好。

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

定义规则

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

代码检查（Code linting）是一种极好的基于规则的反馈形式。反馈越深入越好。例如，生成 TypeScript 并对其进行检查通常比生成纯 JavaScript 更好，因为它为您提供了多个额外的反馈层次。

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

视觉反馈

当使用智能体完成视觉任务时，比如 UI 生成或测试，视觉反馈（以截图或渲染图的形式）会很有帮助。例如，如果发送一封带有 HTML 格式的电子邮件，您可以对生成的邮件进行截图，并将其提供给模型进行视觉验证和迭代优化。然后模型会检查视觉输出是否与请求相符。

例如：

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

使用像 Playwright 这样的 MCP 服务器，您可以自动化这个视觉反馈循环——对渲染的 HTML 进行截图，捕获不同的视口尺寸，甚至测试交互元素——所有这些都在您的智能体工作流程中完成。

Claude 对智能体生成的电子邮件正文提供视觉反馈。

来自大语言模型（LLM）的视觉反馈可以为您的智能体提供有用的指导。

LLM 作为评判者

您也可以让另一个语言模型根据模糊的规则来“评判”您的智能体的输出。这通常不是一个非常稳健的方法，并且可能会有严重的延迟权衡，但对于那些任何性能提升都值得付出代价的应用来说，它可能会有所帮助。

我们的电子邮件智能体可能会有一个单独的子智能体来评判其草稿的语气，看它们是否与用户以前的消息风格相符。

测试和改进您的智能体

在您完成几次智能体循环之后，我们建议测试您的智能体，并确保它为任务做好了充分的准备。改进智能体的最佳方法是仔细查看其输出，特别是失败的案例，并设身处地地为它着想：它是否有合适的工具[工具]来完成工作？

在评估您的智能体是否准备好完成其工作时，还可以问以下一些问题：

  • 如果您的智能体误解了任务，它可能缺少关键信息。您能否改变搜索 API 的结构，使其更容易找到所需信息？
  • 如果您的智能体在某项任务上反复失败，您能否在工具调用中添加一个正式的规则来识别和修复这个失败？
  • 如果您的智能体无法修复其错误，您能否给它提供更有用或更有创意的工具来用不同的方法解决问题？
  • 如果您在添加功能时，智能体的性能有所波动，请根据客户使用情况构建一个有代表性的测试集，用于程序化评估（或 evals）。

开始使用

Claude Agent SDK 通过让 Claude 访问一台可以编写文件、运行命令和迭代工作的电脑，使构建自主智能体变得更加容易。

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

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