Created time
Apr 2, 2026 05:30 PM
category
library
date
Sep 25, 2025
status
Published
icon
password
slug
using-claude-code-sdk-to-build-agents
summary
使用Claude Agent SDK构建智能体的主题是如何利用这一工具创造高效的自主智能体，通过提供程序员所需的工具和能力，使其能够在多种任务中表现出色。
tags
Claude
工程实践
Agent
type
post
原文链接：https://claude.com/blog/building-agents-with-the-claude-agent-sdk 发布时间：2025年9月29日
去年，我们分享了与客户共同打造高效智能体（agents）过程中积累的经验。此后，我们推出了 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 命令、读写文件、搜索文件的能力，它就可以读取 CSV、爬取网页、生成可视化图表、分析数据指标，完成各种数字化工作——本质上，就是用一台电脑创造通用智能体。
Claude Agent SDK 的核心设计哲学正在于此：给你的智能体一台电脑，让它像人一样工作。
开启新一代智能体
我们相信，给 Claude 一台电脑，能解锁前所未有的智能体能力。举几个例子，开发者可以用我们的 SDK 构建：
- 金融智能体：理解你的投资组合与目标，通过调用外部 API、存储数据、运行计算代码，帮你评估投资机会。
- 个人助理智能体：帮你订机票、管日历、安排约会、整理简报，连接你的内部数据源，跨应用追踪上下文。
- 客服智能体：处理高模糊度的用户请求（如工单），收集和审查用户信息、调用外部 API、回复用户，并在必要时转接人工。
- 深度研究智能体：在大型文档库中进行全面研究，搜索文件系统、分析综合多方信息、交叉比对数据，生成详细报告。
这只是其中一部分。本质上，该 SDK 为你提供了构建任何自动化工作流智能体所需的基础组件。
构建你的智能体循环
在 Claude Code 中，Claude 通常在一个特定的反馈循环中运作：收集上下文 → 采取行动 → 验证工作 → 重复。
这个循环为我们思考其他智能体及其所需能力提供了一个清晰的框架。下面，我们将以在 Claude Agent SDK 中构建一个邮件智能体为例，逐一展开说明。
一、收集上下文
在开发智能体时，不只是给它写一段提示词，还要让它能够主动获取并更新自己的上下文。以下是 SDK 的几项关键能力：
智能体搜索与文件系统
文件系统，本质上是一个可以被拉入模型上下文的信息仓库。
当 Claude 遇到大型文件（如日志或用户上传内容）时，它会自主决定如何通过
grep、tail 等 bash 脚本把所需内容载入上下文。智能体的文件夹与文件结构，本身就是一种上下文工程（context engineering）。以邮件智能体为例：它可以将历史对话存储在"Conversations"文件夹中，当用户提问时，直接在这些记录里检索相关上下文。
来自大语言模型（LLM）的视觉反馈，可以为你的智能体提供有效指导。
语义搜索
相比智能体搜索，语义搜索通常更快，但准确度偏低、维护成本更高、透明度也较差。它的原理是：将相关上下文切分为"块"，嵌入为向量，再通过向量查询来检索概念。
鉴于其局限性，我们建议先从智能体搜索起步，只有在确实需要更快速的结果或更多样化的检索方式时，再引入语义搜索。
子智能体（Subagents）
Claude Agent SDK 原生支持子智能体。子智能体有两大核心用途：
- 并行化：启动多个子智能体同时处理不同任务，大幅提升效率。
- 上下文管理：子智能体拥有独立的上下文窗口，只将关键信息回传给主编排者，而非全量上下文——非常适合从大量信息中筛选有效内容的场景。
以邮件智能体为例：我们可以赋予它"搜索子智能体"的能力，并行启动多个子智能体，每个子智能体针对邮件历史运行不同查询，只返回相关摘要，而非完整的邮件链。
压缩（Compaction）
长时间运行的智能体，上下文管理至关重要。Claude Agent SDK 的压缩功能会在接近上下文上限时自动总结早期消息，确保智能体不会因上下文耗尽而中断——这一特性源自 Claude Code 的压缩斜杠命令。
二、采取行动
收集好上下文后，你需要给智能体足够灵活的行动手段。
工具（Tools）
工具是智能体执行任务的核心构建块。工具在 Claude 的上下文窗口中非常显眼，是 Claude 决策时优先考虑的行动方式。因此，你应该精心设计工具，以最大化上下文效率。更多最佳实践可参考我们的博客文章《为智能体编写高效工具》。
你的工具，应该就是你希望智能体采取的主要行动。 了解如何在 Claude Agent SDK 中制作自定义工具。
对于邮件智能体，我们可以将
fetchInbox（获取收件箱）或 searchEmails（搜索邮件）定义为智能体最核心、最高频的动作。Bash 与脚本
Bash 是一把万能钥匙，让智能体能够充分利用电脑灵活地完成工作。
以邮件智能体为例：用户的重要信息可能藏在附件里。Claude 可以编写代码下载 PDF、转换为文本，再通过脚本搜索有价值的内容，如下图所示：
来自大语言模型（LLM）的视觉反馈，可以为你的智能体提供有效指导。
代码生成
Claude Agent SDK 在代码生成上表现尤为突出——这背后有其深刻原因。代码精确、可组合、可无限复用，是需要可靠执行复杂操作的智能体的理想输出形式。
在构建智能体时，不妨问自己：哪些任务可以通过代码表达？通常，答案能解锁意想不到的强大能力。
一个典型案例：我们最近在 Claude.ai 推出的文件创建功能，完全依赖代码生成。Claude 编写 Python 脚本来生成 Excel 表格、PowerPoint 演示文稿和 Word 文档，从而保证格式的高度一致性，并实现其他方式难以做到的复杂功能。
在邮件智能体中，如果我们希望允许用户为收件箱创建规则，可以让 Claude 生成相应代码，在触发条件满足时自动执行：
来自大语言模型（LLM）的视觉反馈，可以为你的智能体提供有效指导。
MCPs
模型上下文协议（MCP） 提供了与外部服务的标准化集成方式，自动处理身份验证和 API 调用。这意味着你可以将智能体接入 Slack、GitHub、Google Drive 或 Asana 等工具，无需自己编写集成代码，也不必手动管理 OAuth 流程。
以邮件智能体为例：我们可能需要"搜索 Slack 消息"来了解团队背景，或"查询 Asana 任务"来确认是否已有人跟进某个客户请求。有了 MCP 服务器，这些集成开箱即用——你的智能体只需调用
search_slack_messages 或 get_asana_tasks 等工具，剩下的交给 MCP 处理。持续壮大的 MCP 生态意味着：随着越来越多预构建集成的出现，你可以快速为智能体扩展新能力，专注于智能体的行为设计本身。
三、验证你的工作
Claude Agent SDK 通过评估工作输出来完成整个智能体循环。能够检查并改进自身输出的智能体，从根本上更可靠——它们能在错误累积前发现问题，在偏离目标时自我修正，并在迭代中持续进化。
关键在于：给 Claude 提供具体的评估方式。以下是我们验证有效的三种方法：
定义规则
最有效的反馈形式，是为输出制定明确的规则，并说明哪些规则未通过及原因。
代码检查（Linting）是一种极佳的基于规则的反馈形式——反馈越详细越好。例如，生成 TypeScript 并进行检查，通常比生成纯 JavaScript 效果更好，因为它提供了多层额外的约束与反馈。
在生成邮件时，你可能希望 Claude 检查：邮件地址是否有效（无效则报错），以及用户是否曾给该收件人发过邮件（若没有则发出警告）。
视觉反馈
当智能体处理 UI 生成或界面测试等视觉任务时，以截图或渲染图形式提供的视觉反馈非常有价值。
以发送 HTML 格式邮件为例：你可以截取生成邮件的图像并回传给模型，让它进行视觉验证和迭代优化。模型会逐项检查视觉输出是否达标，包括：
- 布局——元素位置是否正确？间距是否合适？
- 样式——颜色、字体、格式是否符合预期？
- 内容层级——信息呈现顺序是否清晰？重点是否突出？
- 响应性——是否存在错位或拥挤的情况？
借助 Playwright 等 MCP 服务器，你可以将这个视觉反馈循环完全自动化——截取渲染后的 HTML、捕捉不同视口尺寸，甚至测试交互元素——所有操作都在智能体工作流内完成。
来自大语言模型（LLM）的视觉反馈，可以为你的智能体提供有效指导。
LLM 作为裁判
你还可以让另一个语言模型，依据模糊规则来"评判"智能体的输出。这种方法通常不够稳健，且可能带来明显的延迟代价，但对于那些性能提升价值远超延迟成本的应用场景，仍然值得一试。
以邮件智能体为例：我们可以设置一个专职的"裁判子智能体"，专门评估草稿的语气是否与用户历史消息的风格相符。
测试并持续打磨你的智能体
完成几轮智能体循环后，我们建议系统地测试你的智能体，确认它真的能胜任任务。
改进智能体最有效的方法，是仔细复盘它的输出，尤其是失败案例，并设身处地为它着想：它是否具备完成这项工作所需的合适工具？
在评估智能体是否"装备到位"时，可以参考以下几个问题：
- 如果智能体误解了任务，可能是缺少关键信息。能否调整搜索 API 的结构，让它更容易找到所需内容？
- 如果智能体在某类任务上反复失败，能否在工具调用中加入正式规则，帮助它识别并修复错误？
- 如果智能体无法自主修复错误，能否提供更有用或更具创意的工具，让它用不同方式解决问题？
- 如果随着功能增加，智能体性能出现波动，应基于真实用户使用情况构建具代表性的测试集，进行程序化评估（evals）。
开始使用
Claude Agent SDK 通过让 Claude 访问电脑——编写文件、执行命令、迭代优化——大幅降低了构建自主智能体的门槛。
牢记智能体循环的三个核心环节（收集上下文 → 采取行动 → 验证工作），你就能构建出易于部署和持续迭代的可靠智能体。
今天就可以开始使用 Claude Agent SDK。 对于已在该 SDK 上进行开发的开发者，我们建议参考迁移指南，升级至最新版本。
致谢
作者：Thariq Shihipar；笔记与编辑：Molly Vorwerck, Suzanne Wang, Alex Isken, Cat Wu, Keir Bradwell, Alexander Bricken & Ashwin Bhat。