介绍 Claude Agent SDK（原 Claude Code SDK），助建多类智能体，含构建循环、测试优化及入门方式。原文链接：https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk

1 Claude Agent SDK 简介

Claude Agent SDK 是一套工具集合，助力开发者基于 Claude Code 构建功能强大的智能体（Agent）。本文将详细介绍该 SDK 的入门方法，并分享我们在实践中总结的最佳实践。

去年，我们曾与客户携手，分享了构建高效智能体的相关经验。自那以后，我们推出了 Claude Code—— 这是一款具备智能体特性的编码解决方案，最初开发的目的是提升 Anthropic 内部开发者的工作效率。

在过去的几个月里，Claude Code 的功能已远超 “编码工具” 的范畴。在 Anthropic 内部，我们已将其应用于深度研究、视频创作、笔记记录等众多非编码场景。事实上，公司几乎所有核心的智能体循环（Agent Loop），如今都由它提供支持。

换言之，为 Claude Code 提供动力的智能体架构（即此前的 Claude Code SDK），同样能够支持其他各类智能体的运行。为了体现这一更广泛的应用愿景，我们决定将 “Claude Code SDK” 更名为 “Claude Agent SDK”。

在本文中，我们将重点阐述开发 Claude Agent SDK 的核心原因、如何使用该 SDK 构建自定义智能体，以及分享团队在部署过程中总结的最佳实践。

2 核心设计原则：为 Claude 赋予 “计算机访问权”

Claude Code 的核心设计原则是：Claude 需要拥有程序员日常工作中使用的各类工具。它应能在代码库中查找合适的文件、编写与编辑文件、检查代码语法（Lint）、运行代码、调试程序，有时还需反复执行这些操作，直至代码成功运行。

我们发现，通过让 Claude（借助终端）访问用户的计算机，它便能像程序员一样完成编码工作。

这一设计同样让 Claude 在非编码任务中具备高效能力：通过为其提供运行 bash 命令、编辑文件、创建文件及搜索文件的工具，Claude 可以读取 CSV 文件、搜索网页、生成可视化内容、解析数据指标，进而完成各类数字化工作 —— 简言之，它能借助计算机构建 “通用智能体”。因此，Claude Agent SDK 的核心设计原则可概括为：为智能体赋予计算机访问权，使其能像人类一样开展工作。

3 可构建的新型智能体类型

我们相信，为 Claude 赋予计算机访问权，能解锁更高效的智能体构建能力。例如，借助该 SDK，开发者可构建以下类型的智能体：

• 金融智能体（Finance agents）：这类智能体能够理解用户的投资组合与目标，通过访问外部 API、存储数据并运行代码进行计算，帮助用户评估投资方案。
• 个人助理智能体（Personal assistant agents）：可连接内部数据源、跨应用跟踪上下文，协助用户预订行程、管理日历、安排约会、整理简报等。
• 客户支持智能体（Customer support agents）：能处理模糊性较高的用户请求（如客户服务工单），具体包括收集与查看用户数据、连接外部 API、回复用户消息，以及在必要时将问题升级至人工处理。
• 深度研究智能体（Deep research agents:）：可通过搜索文件系统、分析整合多源信息、跨文件交叉验证数据、生成详细报告等方式，对大型文档集进行全面研究。

除此之外，该 SDK 还具备更广泛的应用潜力。其核心价值在于提供了 “基础构建模块”，开发者可基于此为任何需要自动化的工作流构建专属智能体。

4 构建智能体循环（Agent Loop）

在 Claude Code 中，Claude 通常按照特定的反馈循环运行：收集上下文→执行操作→验证结果→重复循环。

智能体通常遵循 “收集上下文→执行操作→验证结果→重复循环” 这一特定反馈流程。这一框架为设计其他类型的智能体、明确其应具备的能力提供了清晰思路。下文将以 “使用 Claude Agent SDK 构建邮件智能体” 为例，详细拆解这一流程。

4.1 收集上下文

开发智能体时，不能仅为其提供提示词（Prompt），还需让它能够主动获取并更新自身的上下文信息。以下是 SDK 中的关键功能如何助力这一环节：

4.1.1 智能体搜索（Agentic Search）与文件系统

文件系统存储着可被加载到模型上下文中的信息。

当 Claude 遇到日志、用户上传文件等大型文件时，会通过grep、tail等 bash 脚本，决定如何将这些文件加载到上下文当中。本质上，智能体的文件夹与文件结构，本身就是一种 “上下文工程”。

以邮件智能体为例，我们可将历史对话存储在名为 “Conversations” 的文件夹中。当用户询问历史对话相关问题时，智能体便能通过搜索该文件夹获取上下文。

4.1.2 语义搜索（Semantic Search）

语义搜索通常比智能体搜索速度更快，但准确性更低、维护难度更高且透明度较差。其流程包括：将相关上下文 “分块”（Chunking）、将这些块转换为向量嵌入（Embedding），然后通过查询向量来搜索相关概念。鉴于其局限性，我们建议优先使用智能体搜索；仅当需要更快的结果或更多样化的搜索方式时，再考虑添加语义搜索功能。

4.1.3 子智能体（Subagents）

Claude Agent SDK 默认支持子智能体功能。子智能体的价值主要体现在两方面：

• 并行处理：可启动多个子智能体，同时处理不同任务；
• 上下文管理：子智能体拥有独立的上下文窗口，仅会将相关信息反馈给 “主智能体”（Orchestrator），而非传递全部上下文。这一特性使其特别适合处理 “需筛选大量信息、且大部分信息无用” 的任务。

在设计邮件智能体时，我们可为其添加 “搜索子智能体” 功能：主智能体可并行启动多个搜索子智能体，让它们针对用户的邮件历史执行不同查询，并仅返回相关摘录（而非完整邮件线程）。

4.1.4. 上下文压缩（Compaction）

当智能体长时间运行时，上下文维护变得至关重要。Claude Agent SDK 的 “压缩功能” 会在上下文接近长度限制时，自动总结之前的消息，避免智能体出现 “上下文耗尽” 的问题。该功能基于 Claude Code 的 “压缩斜线命令”（Compact Slash Command）构建。

4.2 执行操作

收集完上下文后，需为智能体提供灵活的操作方式：

4.2.1 工具（Tools）

工具是智能体执行操作的核心构建模块。在 Claude 的上下文窗口中，工具会被优先展示，因此智能体在决定如何完成任务时，会优先考虑使用这些工具。这意味着开发者需谨慎设计工具，以最大化上下文利用效率。更多最佳实践可参考我们的博客文章《使用智能体为智能体编写高效工具》（Writing effective tools for agents – with agents）。

【anthropic】Writing effective tools for agents — with agents借助智能体编写高效的智能体工具

简言之，工具应对应智能体最核心、最常用的操作。如需了解如何在 Claude Agent SDK 中创建自定义工具，可参考相关文档。

以邮件智能体为例，我们可将fetchInbox（获取收件箱）、searchEmails（搜索邮件）等定义为其核心且高频的操作工具。

4.2.2. Bash 命令与脚本

Bash 是一种通用工具，可让智能体借助计算机完成灵活的任务。

在邮件智能体场景中，用户可能会在邮件附件中存储重要信息。此时 Claude 可通过编写代码实现以下操作：下载 PDF 附件、将其转换为文本格式、搜索文本中的关键信息，具体流程如下图所示：

4.2.3  代码生成（Code Generation）

Claude Agent SDK 在代码生成方面表现突出，这背后有充分的原因：代码具有精确性、可组合性和无限可复用性，对于需要可靠执行复杂操作的智能体而言，是理想的输出形式。

开发智能体时，可思考一个问题：哪些任务适合通过代码来实现？往往这一问题的答案能为智能体解锁重要能力。

例如，我们近期在 Claude.AI 中推出的 “文件创建” 功能，完全依赖代码生成：Claude 通过编写 Python 脚本，创建 Excel 表格、PowerPoint 演示文稿和 Word 文档，确保格式一致性与复杂功能的实现 —— 这些若通过其他方式则难以达成。

在邮件智能体中，若需支持用户为收件箱邮件创建规则，可通过编写代码来响应相关事件，具体流程如下图所示：

4.2.4. 模型上下文协议（MCP）

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

以邮件智能体为例，若需 “搜索 Slack 消息” 以了解团队上下文，或 “查看 Asana 任务” 以确认是否已有人被分配处理某客户请求，借助 MCP 服务器，这些集成可 “开箱即用”—— 智能体只需调用search_slack_messages（搜索 Slack 消息）、get_asana_tasks（获取 Asana 任务）等工具，后续操作均由 MCP 自动处理。

不断扩展的 MCP 生态系统意味着，随着更多预置集成的推出，开发者可快速为智能体添加新能力，从而将精力集中在智能体的行为设计上。

4.3 验证结果

Claude Code SDK 通过 “评估自身工作” 完成智能体循环。能够检查并优化自身输出的智能体，本质上更可靠：它们能在错误扩大前及时发现问题、在偏离目标时自我修正，并通过迭代不断提升性能。

关键在于为 Claude 提供 “可落地的结果评估方式”。以下是我们实践中验证有效的三种方法：

4.3.1 定义规则（Defining Rules）

最有效的反馈方式是：为输出结果制定清晰规则，然后明确指出哪些规则未被满足及原因。

代码语法检查（Code Linting）是 “基于规则反馈” 的典型例子，反馈越深入，效果越好。例如，生成 TypeScript 代码并进行语法检查，通常比生成纯 JavaScript 代码更优 —— 因为 TypeScript 能提供更多层的反馈。

在生成邮件时，可让 Claude 检查两项规则：一是邮件地址是否有效（若无效则抛出错误），二是用户是否曾向该地址发送过邮件（若未发送则抛出警告）。

4.3.2. 视觉反馈（Visual Feedback）

当智能体执行 UI 生成、测试等视觉相关任务时，视觉反馈（如截图、渲染图）会非常有帮助。例如，若需发送带 HTML 格式的邮件，可对生成的邮件进行截图，并将截图反馈给模型，由模型进行视觉验证与迭代优化 —— 模型会检查视觉输出是否符合预期要求，具体包括：

• 布局：元素位置是否正确？间距是否合适？
• 样式：颜色、字体、格式是否符合预期？
• 内容层级：信息呈现顺序是否合理？重点是否突出？
• 响应式：在不同视图下是否出现错乱或拥挤问题？（注：单张截图的视图信息有限）

通过 Playwright 等 MCP 服务器，可自动化这一视觉反馈循环 —— 在智能体的workflow中，自动对渲染后的 HTML 进行截图、捕获不同视图尺寸，甚至测试交互元素。

4.4.3. 以 LLM 为评判者（LLM as a Judge）

也可让另一个语言模型根据 “模糊规则” 评估智能体的输出。这种方法通常稳健性较低，且会带来较高的延迟，但对于 “性能提升优先级高于成本” 的应用场景，仍有一定帮助。
例如，可为邮件智能体配置一个独立的子智能体，让其根据用户历史消息的风格，评判邮件草稿的语气是否合适。

5 测试与优化智能体

在完成多次智能体循环后，建议对智能体进行测试，确保其具备完成任务所需的能力。优化智能体的最佳方式是：仔细分析其输出（尤其是失败案例），并换位思考：它是否拥有完成任务所需的合适工具？

在评估智能体是否 “装备齐全” 时，还可思考以下问题：

• 若智能体误解任务，可能是缺少关键信息 —— 能否调整搜索 API 的结构，使其更易找到所需信息？
• 若智能体反复在某一任务上失败，能否在工具调用中添加正式规则，以识别并修复该问题？
• 若智能体无法自行修正错误，能否为其提供更实用或更具创造性的工具，帮助其换一种思路解决问题？
• 若添加新功能后智能体性能波动，能否基于客户使用场景，构建具有代表性的测试集，用于程序化评估（即 “Evals”）？

6 入门指南

Claude Agent SDK 通过赋予 Claude“文件写入、命令运行、迭代优化” 的计算机访问权，降低了自主智能体的构建难度。

牢记 “收集上下文→执行操作→验证结果” 的智能体循环，即可构建出可靠、易部署、可迭代的智能体。

您可立即开始使用 Claude Agent SDK。对于已基于旧版 SDK 开发的开发者，建议参考《迁移指南》（this guide），将现有项目迁移至最新版本。

致谢

本文由萨里克・希希帕尔（Thariq Shihipar）撰写，莫莉・沃尔沃克（Molly Vorwerck）、苏珊娜・王（Suzanne Wang）、亚历克斯・伊斯肯（Alex Isken）、吴凯特（Cat Wu）、基尔・布拉德韦尔（Keir Bradwell）、亚历山大・布里肯（Alexander Bricken）及阿什温・巴特（Ashwin Bhat）提供注释与编辑支持。