Anthropic 官方《用 Claude Agent SDK 构建智能体》

非常符合我的认知。claude code的用户不仅仅是程序员。相反，他是目前最成熟的agent框架。所有人，包括程序员、业务，都应该尽快拥抱，放弃掉workflow编排工具。熟练使用面向未来的工具，才是个人增值最快的方式。

发布时间：2025 年 9 月 29 日

Claude Agent SDK 是一组工具，帮助开发者在 Claude Code 之上构建强大的智能体。在本文中，我们将介绍如何开始使用，并分享我们在实践中总结的最佳实践。

为什么要构建 Claude Agent SDK

去年，我们与客户一起分享了构建高效智能体的经验。自那以来，我们发布了 Claude Code，这是我们最初为提升 Anthropic 内部开发者生产力而打造的 agentic 编程解决方案。

在过去的几个月里，Claude Code 已经远不止是一个编程工具。在 Anthropic，我们用它做过深度研究、视频制作、笔记记录，以及无数其他非编程场景。

换句话说，Claude Code 背后的 agent harness （Claude Code SDK）完全可以支持更多类型的智能体。为了反映这一更广阔的愿景，我们将 Claude Code SDK 更名为 Claude Agent SDK。

本文将重点介绍：

为什么我们要构建 Claude Agent SDK
如何用它构建属于你的智能体
我们在内部部署中总结的最佳实践

让 Claude 拥有一台电脑

Claude Code 的核心设计原则是：Claude 需要开发者日常使用的同类工具。它必须能够在代码库中找到合适的文件、读写文件、检查代码格式、运行代码、调试、修改，有时还需要反复迭代直到代码运行成功。

我们发现，当让 Claude 能访问用户的电脑（通过终端）时，它就具备了像人类程序员一样写代码的能力。

但这也让 Claude 在非编程任务上同样有效。通过运行 bash 命令、读写文件、搜索文件等工具，Claude 可以读取 CSV、搜索网页、制作可视化、解读指标，甚至完成各种数字化工作------换句话说，它可以成为一名通用型"有电脑的智能体"。

创建新的智能体类型

我们认为，让 Claude 拥有一台电脑，解锁了以前难以实现的智能体形态。例如，使用 Claude Agent SDK，开发者可以构建：

金融智能体：理解投资组合与目标，调用外部 API、存储数据并运行计算。
个人助理智能体：帮助预订行程、管理日程、整理简报，连接内部数据源并跨应用跟踪上下文。
客户支持智能体：处理高度模糊的用户请求（如客服工单），收集用户数据、调用外部 API、与用户互动并在必要时升级给人工。
研究型智能体：在大型文档库中执行深度研究，跨文件系统搜索、分析与综合信息，交叉引用数据并生成详细报告。

SDK 提供的原语可以帮助你构建任何工作流需要的智能体。

构建智能体循环

在 Claude Code 中，Claude 通常遵循一个反馈循环：

收集上下文 → 执行操作 → 验证结果 → 重复迭代

这个循环对其他智能体同样适用。以下通过一个"邮件智能体"示例来说明。

收集上下文

智能体不能只依赖提示词，它需要能够 获取并更新自己的上下文。

Agentic Search 与文件系统

文件系统是重要的上下文来源。

当 Claude 遇到大型文件（如日志或用户上传文件），它会用 grep、tail 等 bash 脚本决定如何加载上下文。
文件夹与文件结构本身就是一种上下文工程。

例如，邮件智能体可以把历史对话保存在 Conversations 文件夹中，以便搜索和引用。

语义搜索

语义搜索通常比 agentic search 快，但准确率更低、维护更难、透明度差。它通过切块、向量化并基于概念搜索。

我们建议先用 agentic search，仅在需要速度或多样性时才加语义搜索。

子智能体（Subagents）

Claude Agent SDK 原生支持子智能体，主要好处：

并行化：可以同时处理多个任务。
上下文隔离：子智能体只返回相关信息，而不是整个上下文。

例如，邮件智能体可以启用一个"搜索子智能体"，并行查询邮件历史，再返回相关片段。

压缩（Compaction）

长时间运行的智能体需要维护上下文。Claude Agent SDK 的 compaction 功能 会自动总结旧消息，防止上下文溢出。

执行操作

当收集完上下文后，智能体需要有多样的行动方式。

工具（Tools）

工具是执行的核心。它们会显著出现在 Claude 的上下文窗口中，因此必须慎重设计。

例如，邮件智能体的常用工具可以是：

fetchInbox
searchEmails

Bash 与脚本

Bash 提供了灵活的计算能力。比如，Claude 可以写代码下载 PDF、转为文本并搜索其中信息。

代码生成

Claude Agent SDK 在代码生成上表现尤为强大。代码精准、可复用，非常适合智能体执行复杂任务。

例如，Claude AI 新推出的"文件创建"功能就是通过生成 Python 脚本来创建 Excel、PPT、Word 文档。

在邮件智能体里，可以写代码实现"新邮件自动分拣规则"。

MCP（Model Context Protocol）

MCP 提供了与外部服务的标准化集成（处理认证和 API 调用）。

例如，邮件智能体可调用：

search_slack_messages 搜索 Slack
get_asana_tasks 查询 Asana 任务

开发者无需自己写集成或管理 OAuth。随着 MCP 生态发展，你能快速为智能体扩展功能。

验证工作

一个可靠的智能体必须能 检查并改进自己的结果。Claude Code SDK 提供了三种主要方式：

规则约束：比如用 TypeScript + linter 获得更严格反馈。邮件任务中可检查邮件地址是否合法。
可视化反馈：在生成 HTML 邮件时，Claude 可以截图验证排版、样式、内容层级是否符合要求。
LLM 审核：用另一模型作为"裁判"检查输出，例如判断邮件语气是否一致。

测试与改进智能体

构建循环后，要不断测试与优化：

如果智能体误解任务，可能缺少信息 → 改进搜索 API。
如果反复失败 → 加入更严格的规则或新的工具。
如果效果不稳定 → 构建代表性测试集做程序化评估（evals）。

入门

Claude Agent SDK 通过赋予 Claude 电脑的能力（读写文件、运行命令、迭代任务），让构建自治智能体更简单。

按照 收集上下文 → 执行操作 → 验证结果 的循环，你就能构建出可靠且易于部署的智能体。

你今天就可以开始使用 Claude Agent SDK。

已经在用旧版 SDK 的开发者，可以按迁移指南升级到最新版。