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、如何用它打造你自己的智能体，以及我们团队在落地实践中总结出的最佳实践。

Giving Claude a computer

Claude Code 的核心设计原则是：Claude 需要和程序员日常使用的工具一样的能力。它需要能够在代码库中定位合适的文件、编写和编辑文件、执行代码检查、运行代码、调试、修改，并在必要时迭代执行这些操作直到代码成功。

我们发现，只要让 Claude 通过终端访问用户的电脑，它就拥有像程序员一样写代码所需的一切。

但这也让 Claude 在 Claude Code 中同样擅长处理 非 编码任务。只要赋予它运行 bash 命令、编辑文件、创建文件、搜索文件等工具，Claude 就能读取 CSV 文件、搜索网页、构建可视化、解读指标，以及完成各种数字化工作——简而言之，就是为你的智能体配备一台电脑，让它像人类一样工作，这正是 Claude Agent SDK 的核心设计理念。

Creating new types of agents

我们相信，为 Claude 配备一台电脑，能够释放此前难以实现的智能体能力。例如，借助我们的 SDK，开发者可以构建：

• Finance agents :** 构建能够理解你的投资组合和目标，并可通过访问外部 API、存储数据和运行代码来进行计算、帮助你评估投资的智能体。
• Personal assistant agents. 构建能够帮助你预订行程、管理日程、安排会议、整理简报，并通过连接内部数据源跨应用追踪上下文的智能体。
• Customer support agents: 构建能够处理高模糊度用户请求（如客服工单）的智能体；它们可以收集并审查用户数据、调用外部 API、向用户回信，并在需要时升级给人工。
• Deep research agents : 构建能够在大型文档集合中执行全面调研的智能体；它们可以搜索文件系统、分析并综合多个来源的信息、交叉引用文件中的数据，并生成详尽的报告。

除此之外还有更多场景。本质上，SDK 为你提供了构建任意自动化工作流所需的基础能力。

Building your agent loop

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

这个框架同样适用于其他类型的智能体，并帮助我们思考它们应当具备的能力。为此，我们将以在 Claude Agent SDK 中构建一名邮件智能体为例展开说明。

Gather context

在开发智能体时，你需要提供的不仅仅是一段提示词：它必须能够自行获取并更新上下文。以下是 SDK 中的功能如何提供帮助。

Agentic search and the file system

文件系统代表了可能被加载进模型上下文的信息。

当 Claude 遇到日志或用户上传文件等大文件时，它会通过执行 grep、tail 等 bash 脚本来决定如何把这些内容加载进上下文。本质上，智能体的文件夹与文件结构就是一种上下文工程。

我们的邮件智能体可以把历史对话存放在名为“Conversations”的文件夹中。当用户提问时，它就能在这些记录里检索所需的上下文。

Semantic search

语义搜索通常比自主搜索更快，但准确度较低、维护复杂度更高、透明度也更差。它需要对相关上下文进行“分块”，将这些片段嵌入为向量，然后通过查询向量来查找概念。鉴于这些限制，我们建议先从自主搜索入手，只有在需要更快的结果或更多变体时再补充语义搜索。

Subagents

Claude Agent SDK 原生支持子智能体。子智能体主要有两个好处。首先，它们能够并行化：你可以同时启动多个子智能体去处理不同任务。其次，它们有助于管理上下文：子智能体会使用各自独立的上下文窗口，并只把相关信息返回给调度器，而不是整个上下文。这使得它们非常适合在海量信息中筛选有用内容。

在设计邮件智能体时，我们可以为它提供一个“search subagent”能力。这样，邮件智能体就能并行启动多个搜索子智能体——每个子智能体针对邮件历史运行不同查询——并只返回相关摘录，而不是完整邮件线程。

Compaction

当智能体长时间运行时，上下文维护至关重要。Claude Agent SDK 的压缩功能会在接近上下文上限时自动总结过往消息，避免智能体耗尽上下文。这一能力源自 Claude Code 的compact 斜杠指令。

Take action

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

Tools

工具是智能体执行任务的主要构件。工具会显著出现在 Claude 的上下文窗口中，因此也是 Claude 在决定如何完成任务时优先考虑的行动。这意味着你应谨慎设计工具，以最大化上下文利用效率。更多最佳实践可参见我们的博文用智能体写出高效工具。

因此，你的工具应当是希望智能体优先执行的核心动作。了解如何在 Claude Agent SDK 中制作自定义工具。

在我们的邮件智能体中，我们可以将“fetchInbox”或“searchEmails”之类的工具定义为最常用的核心操作。

Bash & scripts

Bash 作为通用工具，能够让智能体利用电脑执行灵活的工作。

在邮件智能体中，用户的重要信息可能存放在附件里。Claude 可以编写代码下载 PDF、转换为文本，并在其中搜索有用信息，如下所示：

Code generation

Claude Agent SDK 在代码生成方面表现卓越，这并非偶然。代码具有精确、可组合、可无限复用等特性，使其成为需要可靠执行复杂操作的智能体的理想产出形式。

在构建智能体时，可以思考哪些任务适合以代码形式表达？这个答案往往能带来显著的能力提升。

例如，我们最近发布的在 Claude.AI 中创建文件Claude.AI功能就完全依赖代码生成。Claude 会编写 Python 脚本来创建 Excel 表格、PowerPoint 演示文稿和 Word 文档，从而确保格式一致并实现其他方式难以达成的复杂功能。

在邮件智能体中，我们可能希望允许用户为入站邮件创建规则。为此，我们可以编写代码在相应事件触发时运行：

MCPs

模型上下文协议（Model Context Protocol，简称 MCP）为外部服务提供了标准化集成，自动处理身份验证和 API 调用。这意味着你无需编写自定义集成代码或亲自管理 OAuth 流程，就能将 Slack、GitHub、Google Drive 或 Asana 等工具接入智能体。

对于我们的邮件智能体，我们可以让它调用 search Slack messages 来理解团队上下文，或使用 check Asana tasks 查看是否已有任务被指派负责客户请求。借助 MCP 服务器，这些集成能力即可开箱即用——你的智能体只需调用诸如 search_slack_messages 或 get_asana_tasks 的工具，MCP 会处理剩下的工作。

不断壮大的 MCP 生态意味着，你可以随着预构建集成的增加迅速为智能体扩展新能力，从而把精力集中在智能体行为上。

Verify your work

Claude Code SDK 通过评估工作成果来完成智能体循环。能够自检并改进输出的智能体本质上更加可靠——它们会在错误扩散之前及时捕捉、在偏离目标时自我纠正，并在迭代中持续变得更好。

关键在于为 Claude 提供具体的方法来评估自己的工作。以下是我们认为行之有效的三种方式：

Defining rules

最好的反馈形式是提供清晰定义的规则，并说明哪些规则失败以及原因。

代码检查就是一种优秀的基于规则的反馈。反馈越详细越好。例如，生成 TypeScript 并进行检查通常比直接生成纯 JavaScript 更佳，因为这样可以多获得几层额外反馈。

在生成邮件时，你可能需要让 Claude 检查邮件地址是否有效（若无效则抛出错误），以及用户此前是否给该联系人发过邮件（若发过则给出警告）。

Visual feedback

在使用智能体完成 UI 生成或测试等视觉任务时，截图或渲染等形式的视觉反馈非常有用。例如，在发送带有 HTML 格式的邮件时，你可以对生成的邮件进行截屏，将结果回传给模型，以便进行视觉校验和迭代改进。模型随后会检查视觉输出是否符合需求。

例如：

• Layout - 元素布局是否正确？间距是否恰当？
• Styling - 颜色、字体和格式是否呈现为预期效果？
• Content hierarchy - 信息呈现顺序是否正确？重点是否突出？
• Responsiveness - 界面是否看起来拥挤或异常？（尽管单张截图的视窗信息有限）

使用像 Playwright 这样的 MCP 服务器，你可以自动化这一视觉反馈循环——在智能体工作流中捕捉渲染后的 HTML 截图、覆盖不同视窗尺寸，甚至测试交互元素。

LLM as a judge

你也可以让另一个语言模型根据模糊规则来“评判”智能体的输出。这种方法总体上不够稳健，而且可能带来明显的时延开销，但对于那些追求任何性能提升的应用来说，它仍然有价值。

我们的邮件智能体可以使用一个独立的子智能体来评估草稿邮件的语气，看看它是否与用户先前的消息相契合。

Testing and improving your agent

在多次运行智能体循环后，我们建议对智能体进行测试，确保它胜任任务。改进智能体的最佳方式是仔细检查它的输出，尤其是失败案例，并试着站在它的角度思考：它是否拥有完成工作所需的合适工具？

在评估智能体是否做好准备时，可以自问以下问题：

• 如果智能体误解任务，可能缺失关键信息。你能否调整搜索 API 的结构，让它更易找到所需内容？
• 如果智能体反复在某项任务上失败，你能否在工具调用中添加正式规则来识别并修复该失败？
• 如果智能体无法修正自己的错误，你能否提供更有用或更具创造性的工具，让它以不同方式解决问题？
• 如果随着功能增加智能体表现波动，你能否基于客户使用方式构建代表性的测试集，用于程序化评估（或称 evals）？

Getting started

Claude Agent SDK 通过让 Claude 使用一台电脑（写文件、运行命令、迭代工作），使构建自治智能体变得更加简单。

只要牢记智能体循环（收集上下文、采取行动、验证结果），你就能构建易于部署与迭代的可靠智能体。

你可以立即开始体验 Claude Agent SDK。对于已经使用这一 SDK 的开发者，我们建议按照这份指南迁移至最新版本。

Acknowledgements

本文由 Thariq Shihipar 撰写，Molly Vorwerck、Suzanne Wang、Alex Isken、Cat Wu、Keir Bradwell、Alexander Bricken 与 Ashwin Bhat 提供笔记与编辑支持。

Get the developer newsletter

获取产品更新、操作指南、社区专题等内容，按月投递至你的收件箱。

如果你希望收到我们的月度开发者通讯，请留下电子邮箱地址。你可以随时取消订阅。