Anthropic 官方正式推出 Claude Agent SDK，这是一套让 AI 像程序员一样操作电脑、构建自主智能体的强大工具。无论你是想开发金融助手、个人助理、客户支持系统，还是深度研究引擎，本教程将带你从零起步，掌握智能体构建的完整流程与最佳实践。
核心设计：给 Claude 一台电脑
Claude Agent SDK 背后的核心设计理念非常直接：Claude 需要和程序员一样，拥有相同的日常工具。这意味着智能体必须能够在代码库中查找文件、编写和编辑文件、进行代码检查（lint）、运行、调试，并在此过程中不断迭代直至成功。
Anthropic 团队发现，通过终端给予 Claude 访问用户计算机的权限，它就获得了像程序员一样编写代码所需的一切。更重要的是，这也使得 Claude 在处理非编码任务时同样高效。通过运行 bash 命令、编辑、创建和搜索文件，Claude 能够读取 CSV 文件、搜索网页、构建可视化图表、解读指标等，胜任各类数字工作——简而言之，成为一个 拥有计算机的通用智能体。
让智能体像人类一样使用计算机工作，这正是 Claude Agent SDK 的关键设计思路。
四大应用场景：你可以用智能体做什么？
Anthropic 认为，为 Claude 配备一台“电脑”，能够解锁过去难以有效实现的智能体能力。利用该 SDK，开发者可以构建以下四种典型智能体：
- 金融智能体：理解投资组合和目标，通过访问外部 API、存储数据和运行代码来帮助评估投资。
- 个人助理智能体：连接内部数据源，跨应用追踪上下文，帮助预订差旅、管理日历、安排会议、整理简报等。
- 客户支持智能体：处理高模糊性的用户请求（如客服工单），通过收集和审查用户数据、连接外部 API、回复用户，并在必要时将问题升级给人类。
- 深度研究智能体：在大型文档集合中进行全面研究，通过搜索文件系统、分析和综合多源信息、交叉引用数据，并生成详细报告。
其核心是，该 SDK 提供了构建智能体所需的基础模块，以自动化你想要的任何工作流。
智能体开发黄金循环：收集上下文 → 采取行动 → 验证工作 → 重复
在实践中，Claude 通常遵循一个特定的反馈循环进行操作：收集上下文 → 采取行动 → 验证工作 → 重复。
这个循环为思考如何构建其他类型的智能体以及应赋予它们何种能力，提供了一个有效的框架。下面，我们将以构建一个 邮件智能体 为例，逐步拆解这个过程。
第一步：收集上下文
开发智能体时，不能只给它一个提示，而是要让它能够获取并更新自己的上下文。
智能体搜索与文件系统
文件系统代表了可以被模型调用的潜在信息。当遇到日志等大文件时，Claude 会自行决定使用 grep、tail 等 bash 脚本来加载最相关的部分。本质上，智能体的文件夹和文件结构本身，就成为了一种 上下文工程。例如，邮件智能体可以将过去的对话存储在名为 'Conversations' 的文件夹中，以便在需要时进行搜索。
子智能体 (Subagents)
SDK 默认支持子智能体。其优势有二：一是并行化，可以同时启动多个子智能体处理不同任务；二是上下文管理，子智能体在隔离的上下文中工作，只将相关信息返回给主控者，非常适合处理需要从海量信息中筛选少量有用数据的任务。例如，邮件智能体可以并行启动多个“搜索子智能体”，分别查询邮件历史，并只返回相关的邮件摘要。
压缩 (Compaction)
当智能体长时间运行时，上下文维护至关重要。当接近上下文窗口限制时，SDK 的 compact 功能会自动总结之前的消息，确保智能体不会耗尽上下文空间。
语义搜索
语义搜索虽然速度通常比智能体搜索快，但准确性较低，且维护更困难、透明度更差。Anthropic 建议从智能体搜索开始，仅在需要更快速度或更多样化结果时才引入语义搜索。
小提示： 如果你的智能体处理的是大量小文件（如邮件、笔记），优先使用文件系统搜索 + grep 组合，比语义搜索更可靠、更容易调试。
第二步：采取行动
收集完上下文后，你需要为智能体提供灵活的行动方式。
工具 (Tools)
工具是智能体执行任务的主要构建模块。它们在 Claude 的上下文窗口中非常突出，是模型决定如何完成任务时优先考虑的选项。因此，你需要精心设计工具以最大化上下文效率。例如，为邮件智能体定义 "fetchInbox" 或 "searchEmails" 等核心工具。
Bash 与脚本
Bash 作为一个通用工具，能让智能体灵活地使用计算机。例如，邮件智能体可以编写代码来下载邮件附件（如 PDF），将其转换为文本，然后搜索其中的关键词（如“invoice”）。
pdftotext document.pdf - | grep -n "invoice" | tail -10代码生成
Claude Agent SDK 擅长代码生成。代码具有精确、可组合和可复用的特性，是执行复杂操作的理想选择。例如，Claude.ai 中创建 Excel、PPT 和 Word 文档的功能，完全依赖于生成 Python 脚本来实现。对于邮件智能体，我们可以让它生成代码，为收到的邮件创建自动化规则：
async function onEmailReceived(email) {
const isFromCustomer = email.from.includes('@customer.com') || /* ... */;
if (!isFromCustomer) return;
const isEmailUrgent = await askLLM(`Does this email seem urgent: ${renderEmail(email)}, return TRUE OR FALSE`);
if (isEmailUrgent === "TRUE" && isFromCustomer) {
forwardEmail(email, { to: 'teamlead@company.com' });
createTask({ title: `Urgent: Respond to ${email.from}` });
}
}MCPs (模型上下文协议)
Model Context Protocol (MCP) 提供了与外部服务的标准化集成，能自动处理身份验证和 API 调用。这意味着你可以轻松将智能体连接到 Slack、GitHub、Google Drive 或 Asana 等工具，无需编写自定义集成代码或管理 OAuth 流程。
小提示： 优先使用 MCP 连接外部服务，而不是自己写 API 调用代码——MCP 自动处理认证和错误重试，能显著减少你的维护成本。
第三步：验证工作
智能体循环的最后一步是评估其工作。能够检查并改进自身输出的智能体更加可靠。关键在于给予 Claude 评估工作的具体方法。
定义规则
最有效的反馈形式是提供明确的输出规则，并在规则未被满足时解释原因。代码检查（Code linting） 就是一个典型的基于规则的反馈。例如，生成 TypeScript 并对其进行检查，通常比直接生成纯 JavaScript 更好，因为它提供了更多层次的反馈。
视觉反馈
在处理 UI 生成或测试等视觉任务时，截图或渲染图形式的视觉反馈非常有帮助。例如，在生成 HTML 格式的邮件后，可以将其截图并返回给模型进行视觉验证，检查布局、样式、内容层级、响应性等是否符合要求。使用像 Playwright 这样的 MCP 服务器，可以自动化整个视觉反馈循环。
LLM 作为评判者
你也可以让另一个语言模型根据模糊的规则来“评判”智能体的输出。这种方法通常不够稳健，且会带来延迟，但对于追求极致性能的应用场景可能有所帮助。例如，让一个子智能体来判断邮件草稿的语气是否与用户之前的沟通风格一致。
常见问题： 什么时候用规则检查，什么时候用 LLM 评判？
规则检查（如 lint、类型检查）速度快、确定性高，适合可以明确描述的问题。LLM 评判适合主观性强、难以用规则定义的任务（如语气、创意风格）。建议优先使用规则，只有在规则无法覆盖时才引入 LLM 评判。
测试与改进你的智能体
在多次迭代智能体循环后，你需要对其进行测试，确保它能胜任任务。最好的改进方法是仔细检查其输出，尤其是在失败的案例中，并设身处地思考：它是否拥有完成这项工作的合适工具？
以下是一些评估时可以自问的问题：
- 如果智能体误解了任务，是否缺少关键信息？能否调整搜索 API 的结构，让它更容易找到所需内容？
- 如果智能体在某个任务上反复失败，能否在工具调用中添加一个正式规则来识别和修复该失败？
- 如果智能体无法修复自己的错误，能否提供更有用或更有创意的工具来解决问题？
- 如果智能体的性能随着功能增加而波动，是否应根据客户使用情况构建一个代表性的测试集，进行程序化评估？
常见问题： 智能体运行时间长了之后上下文溢出怎么办？
SDK 内置的compact功能会自动压缩历史消息，但建议你主动在关键节点（如完成一个子任务后）调用compact，避免在运行时突然超出限制。同时，保持子智能体任务独立，减少主控节点的上下文压力。
结语
从金融分析到个人助理，从客户支持到深度研究，Claude Agent SDK 为你打开了一扇通往通用智能体的大门。记住黄金循环——收集上下文、采取行动、验证工作、重复迭代——并在实践中不断为智能体补充合适的工具和规则。现在，你已拥有打造自己专属智能体所需的一切知识与最佳实践，开始动手吧！