# 01 【最新】Building agents with the Claude Agent SDK - Agent开发框架的完整构建指南

> **发布时间**：2025年9月29日\
> **原文链接**：<https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk\\>
> **核心定位**：从Claude Code SDK到Claude Agent SDK的战略转型，提供Agent开发的系统性方法论

***

## 📖 文章概览

这是Anthropic最新发布的文章，标志着一个重要的战略转型：**Claude Code SDK正式更名为Claude Agent SDK**，体现了从"编码工具"到"通用Agent框架"的范式升级。

### 关键背景

* **起源**：Claude Code最初是Anthropic内部提升开发者生产力的工具
* **演进**：过去几个月被用于深度研究、视频创作、笔记记录等非编码场景
* **现状**：Claude Code已成为Anthropic几乎所有主要Agent循环的动力来源
* **未来**：Agent SDK将支持更广泛的Agent类型构建

***

## 🎯 核心设计哲学：给Claude一台计算机

### 根本原则

> **关键洞察**：程序员每天使用什么工具，Claude就需要什么工具。

Claude Code的核心设计原则来自一个简单但深刻的观察：

```
程序员的工作流程：
  1. 在代码库中查找相关文件
  2. 编写和编辑文件
  3. Lint代码
  4. 运行代码
  5. 调试
  6. 迭代直到成功

Claude的需求 = 程序员的工具集
```

### 技术实现

通过给Claude访问用户计算机的能力（via Terminal），它获得了：

* 执行Bash命令的能力
* 编辑文件的能力
* 创建和搜索文件的能力

**副作用**：这些通用能力使Claude在**非编码任务**上同样有效：

* 读取CSV文件
* 网络搜索
* 构建可视化
* 解释指标
* 执行各种数字化工作

***

## 🤖 Agent应用场景：从理论到实践

Anthropic提供了四类典型Agent应用案例：

### 1️⃣ 金融Agent

**能力**：

* 理解投资组合和目标
* 评估投资机会
* 访问外部API
* 存储数据
* 运行代码进行计算

**技术栈**：

```
金融Agent = Claude + 金融API + 数据存储 + 计算工具
```

### 2️⃣ 个人助理Agent

**能力**：

* 预订旅行和管理日历
* 安排约会
* 汇总简报
* 连接内部数据源
* 跨应用追踪上下文

**技术栈**：

```
个人助理 = Claude + 日历API + 数据集成 + 上下文管理
```

### 3️⃣ 客户支持Agent

**能力**：

* 处理高度模糊的用户请求
* 收集和审查用户数据
* 连接外部API
* 向用户发送消息
* 必要时升级到人类

**技术栈**：

```
客服Agent = Claude + 用户数据 + 通信工具 + 升级机制
```

### 4️⃣ 深度研究Agent

**能力**：

* 在大型文档集合中进行全面研究
* 搜索文件系统
* 分析和综合多源信息
* 交叉引用数据
* 生成详细报告

**技术栈**：

```
研究Agent = Claude + 文件系统 + 检索工具 + 综合能力
```

***

## 🔄 Agent工作循环：四步反馈模式

Anthropic提出了一个经典的Agent工作模式：

```
┌─────────────┐
│ 1. Gather   │  收集上下文
│   Context   │  
└──────┬──────┘
       ↓
┌──────────────┐
│ 2. Take      │  采取行动
│    Action    │
└──────┬───────┘
       ↓
┌──────────────┐
│ 3. Verify    │  验证工作
│    Work      │
└──────┬───────┘
       ↓
┌──────────────┐
│ 4. Repeat    │  重复循环
│              │
└──────────────┘
```

### 每个阶段的技术细节

***

## 📂 阶段1：收集上下文 (Gather Context)

### 1.1 Agentic Search与文件系统

**核心思想**：文件系统代表**可能**被拉入模型上下文的信息。

**工作方式**：

```python
# 当Claude遇到大文件时
# 它会决定如何加载上下文

# 示例：使用Bash脚本
grep "关键词" large_file.log
tail -n 100 large_file.log
```

**上下文工程**：

* 文件夹和文件结构成为一种**上下文工程形式**
* 命名规范、层级结构、时间戳都提供重要信号

**示例**：

```
# Email Agent的文件结构
/
├── Conversations/           # 历史对话
│   ├── 2025-10/
│   └── 2025-09/
├── Contacts/               # 联系人信息
└── Templates/              # 邮件模板
```

### 1.2 语义搜索 (Semantic Search)

**对比分析**：

| 特性  | Agentic Search | Semantic Search |
| --- | -------------- | --------------- |
| 速度  | 较慢             | 更快              |
| 准确性 | 更高             | 较低              |
| 维护性 | 更容易            | 更困难             |
| 透明度 | 高              | 低               |

**Anthropic建议**：

```
1. 首先使用Agentic Search
2. 仅在需要更快结果或更多变化时添加语义搜索
```

### 1.3 Subagents（子代理）

**核心价值**：

**价值1：并行化**

```python
# 主Agent可以同时启动多个子Agent
main_agent.spawn([
    SubAgent(task="search_emails", query="Q1"),
    SubAgent(task="search_emails", query="Q2"),
    SubAgent(task="search_emails", query="Q3"),
])
```

**价值2：上下文隔离**

* 子Agent使用自己的独立上下文窗口
* 只返回相关信息给协调者
* 避免上下文污染

**示例：Email Agent的搜索子Agent**

```python
# Email Agent使用搜索子Agent
email_agent.create_subagent(
    task="搜索包含'项目A'的邮件",
    return_format="excerpts_only"  # 只返回相关摘录
)

# 而不是返回完整的邮件线程
```

### 1.4 Compaction（压缩）

**问题**：长时间运行的Agent会耗尽上下文。

**解决方案**：自动压缩功能

* 当接近上下文限制时，自动总结之前的消息
* Agent不会耗尽上下文
* 基于Claude Code的`/compact`命令

**实现**：

```python
# 伪代码
if context_length > threshold:
    summary = claude.summarize(previous_messages)
    reset_context(summary)
```

***

## ⚡ 阶段2：采取行动 (Take Action)

### 2.1 Tools（工具）

**核心地位**：

> 工具是Agent执行的**主要构建块**。

**为什么重要**：

* 工具在Claude的上下文窗口中**非常突出**
* 工具是Claude考虑任务时的**主要行动**
* 必须注意工具设计以最大化上下文效率

**最佳实践**：

```markdown
工具应该是你希望Agent采取的**主要行动**

例如，Email Agent的主要工具：
- fetchInbox（获取收件箱）
- searchEmails（搜索邮件）
- sendEmail（发送邮件）
```

**参考文章**：*Writing effective tools for agents – with agents*

### 2.2 Bash & Scripts

**用途**：作为通用工具，允许Agent使用计算机进行灵活工作。

**示例场景**：Email Agent处理附件

```bash
# 用户的重要信息存储在附件中
# Claude可以编写代码来：

# 1. 下载PDF
wget attachment_url -O document.pdf

# 2. 转换为文本
pdftotext document.pdf document.txt

# 3. 搜索信息
grep "关键词" document.txt
```

### 2.3 Code Generation（代码生成）

**核心优势**：

代码是理想的Agent输出，因为：

1. **精确**：没有歧义
2. **可组合**：可以重用和组合
3. **可靠**：可以重复执行

**实战案例**：

**案例1：Claude.AI的文件创建功能**

```python
# Claude编写Python脚本来创建：
- Excel电子表格
- PowerPoint演示文稿
- Word文档

# 确保一致的格式和复杂功能
```

**案例2：Email Agent的规则系统**

```python
# 用户想为入站邮件创建规则
# Claude生成代码在事件发生时运行

def on_email_received(email):
    if "urgent" in email.subject.lower():
        mark_as_important(email)
        notify_user_immediately(email)
    elif email.from_address in spam_list:
        move_to_spam(email)
```

### 2.4 MCPs（Model Context Protocol）

**核心价值**：标准化的外部服务集成

**解决的问题**：

```
传统方式：
每个集成 = 编写自定义代码 + 处理身份验证 + 管理API调用

MCP方式：
每个集成 = 使用现成的MCP Server
```

**Email Agent示例**：

```python
# 无需编写集成代码，直接使用MCP
mcp_tools = [
    "search_slack_messages",   # 搜索Slack
    "get_asana_tasks",         # 获取Asana任务
    "check_calendar_events"    # 检查日历
]

# MCP处理：
# - 身份验证
# - API调用
# - 错误处理
```

**MCP生态系统**：

* GitHub
* Google Drive
* Slack
* Asana
* 持续增长中...

**链接**：<https://github.com/modelcontextprotocol/servers>

***

## ✅ 阶段3：验证工作 (Verify Work)

> **核心理念**：能够检查和改进自己输出的Agent本质上更可靠。

### 三种验证方法

### 3.1 定义规则 (Defining Rules)

**最佳反馈形式**：提供明确定义的规则，然后解释哪些规则失败以及为什么。

**代码Linting的启发**：

```typescript
// TypeScript比纯JavaScript好
// 因为它提供了多个额外的反馈层

// JavaScript
function add(a, b) {
    return a + b;
}

// TypeScript
function add(a: number, b: number): number {
    return a + b;
}

// TypeScript会捕获：
// - 类型错误
// - 参数数量错误
// - 返回类型错误
```

**Email Agent示例**：

```python
# 生成邮件时的验证规则

def validate_email(email):
    # 规则1：验证邮件地址
    if not is_valid_email_address(email.to):
        raise ValidationError("Invalid email address")
    
    # 规则2：检查之前是否发送过
    if not has_sent_before(email.to):
        emit_warning("First time sending to this address")
    
    # 规则3：检查附件大小
    if email.attachment_size > MAX_SIZE:
        raise ValidationError("Attachment too large")
```

### 3.2 视觉反馈 (Visual Feedback)

**适用场景**：UI生成、测试等视觉任务

**工作流程**：

```
1. Agent生成HTML邮件
   ↓
2. 截图渲染的邮件
   ↓
3. 将截图返回给模型
   ↓
4. 模型验证视觉输出
   ↓
5. 迭代改进
```

**验证维度**：

* **布局**：元素位置是否正确？间距是否合适？
* **样式**：颜色、字体、格式是否符合预期？
* **内容层次**：信息是否按正确的顺序呈现？
* **响应式**：是否看起来破损或拥挤？

**技术实现**：

```python
# 使用Playwright MCP Server
from playwright_mcp import Browser

browser = Browser()
screenshot = browser.screenshot(html_content)
feedback = claude.analyze_screenshot(screenshot)
```

### 3.3 LLM作为评判 (LLM as a Judge)

**方法**：使用另一个语言模型"评判"Agent的输出

**特性**：

* **不够稳健**：通常不是非常可靠的方法
* **延迟权衡**：会增加延迟成本
* **适用场景**：当提升性能的价值值得成本时

**Email Agent示例**：

```python
# 单独的子Agent评判草稿的语气
judge_agent = SubAgent(
    task="evaluate_tone",
    input=draft_email,
    reference=previous_emails
)

# 判断是否符合用户的写作风格
feedback = judge_agent.evaluate()
```

***

## 🧪 测试和改进Agent

### 核心方法论

> **最佳改进方式**：仔细查看Agent的输出，特别是失败的案例，并站在Agent的角度思考：它是否拥有完成工作的**正确工具**？

### 关键问题检查清单

#### 1️⃣ Agent误解任务？

**可能原因**：缺少关键信息

**解决方案**：

```python
# 修改搜索API的结构
# 使其更容易找到需要的信息

# Before
def search(query: str) -> List[Document]:
    return search_engine.search(query)

# After
def search_with_context(
    query: str,
    context_type: str,  # "email", "document", "code"
    time_range: Optional[str] = None
) -> List[DocumentWithContext]:
    results = search_engine.search(query, context_type)
    return enrich_with_context(results)
```

#### 2️⃣ Agent重复失败某项任务？

**可能原因**：缺少形式化规则来识别和修复失败

**解决方案**：

```python
# 在工具调用中添加形式化规则

def send_email(to: str, subject: str, body: str):
    # 规则1：检查收件人
    if not validate_recipient(to):
        raise Error("Invalid recipient")
    
    # 规则2：检查主题长度
    if len(subject) > MAX_SUBJECT_LENGTH:
        raise Error("Subject too long")
    
    # 规则3：检查敏感词
    if contains_sensitive_words(body):
        require_confirmation()
```

#### 3️⃣ Agent无法修复错误？

**可能原因**：缺少有用或创造性的工具来换个方式解决问题

**解决方案**：

```python
# 提供替代工具

# 原工具
def search_by_keyword(keyword: str):
    ...

# 新增工具
def search_by_semantic_similarity(text: str):
    ...

def search_by_date_range(start: str, end: str):
    ...

def browse_recent_items(limit: int = 10):
    ...
```

#### 4️⃣ 添加功能后Agent性能波动？

**可能原因**：缺少代表性的测试集

**解决方案**：

```python
# 基于客户使用情况构建测试集

test_cases = [
    # 常见场景
    {"input": "...", "expected": "..."},
    # 边缘情况
    {"input": "...", "expected": "..."},
    # 失败案例
    {"input": "...", "expected": "..."},
]

# 运行程序化评估
for test in test_cases:
    result = agent.run(test["input"])
    assert result == test["expected"]
```

***

## 🚀 开始使用Claude Agent SDK

### 快速开始

**文档链接**：<https://docs.claude.com/en/api/agent-sdk/overview>

**迁移指南**（已在使用SDK的开发者）：\
<https://docs.claude.com/en/docs/claude-code/sdk/migration-guide>

### 核心优势总结

1. **简单易用**：通过给Claude访问计算机来构建自主Agent
2. **循环思维**：始终思考"收集上下文→采取行动→验证工作"
3. **可靠部署**：易于部署和迭代
4. **灵活扩展**：支持广泛的Agent类型

***

## 💡 深度洞察：技术思维转型

### 从"函数"到"Agent"的范式转变

```
传统软件开发：
  输入 → 确定性函数 → 输出
  
Agent开发：
  目标 → 非确定性Agent → 结果
  
差异：
- 不是预定义路径
- 而是动态决策
- 需要验证和迭代
```

### 上下文工程成为新核心

```
传统关注点：
- 算法效率
- 数据结构
- 代码复用

Agent关注点：
- 上下文管理
- 工具设计
- 反馈循环
```

### 工具设计的人机界面类比

> **关键类比**：就像在人机界面（HCI）上投入大量精力一样，应该在代理-计算机界面（ACI）上投入同样多的精力。

**设计原则**：

1. **清晰性**：工具描述必须明确
2. **防错性**（Poka-yoke）：设计使其难以犯错
3. **反馈性**：提供有用的错误信息
4. **一致性**：工具之间保持一致的接口

***

## 🔗 与其他文章的关联

### 前置文章

* **Building effective agents**（2024.12.19）：Agent的基础理论
* **Context engineering**（2025.09.29）：上下文管理深入探讨

### 相关工具文章

* **Writing effective tools for agents**（2025.09.11）：工具设计最佳实践
* **Desktop Extensions**（2025.06.26）：MCP Server的一键安装

### 实践案例

* **Multi-agent research system**（2025.06.13）：多Agent协作的实战案例
* **Claude Code Best Practices**（2025.04.18）：Agentic Coding的最佳实践

***

## 🎯 实践建议

### 对开发者

1. **从简单开始**

   ```
   不要试图一次构建复杂的Multi-Agent系统
   先构建单个Agent，验证其有效性
   ```
2. **投资工具设计**

   ```
   工具设计 = Agent能力的上限
   花时间优化工具描述和接口
   ```
3. **建立反馈循环**

   ```
   测试 → 观察失败 → 改进工具 → 重新测试
   ```

### 对产品经理

1. **理解Agent的非确定性**

   ```
   Agent != 传统软件
   需要设计监督和升级机制
   ```
2. **选择合适的场景**

   ```
   适合Agent的场景：
   - 任务步骤不可预测
   - 需要动态决策
   - 能够接受一定的错误率
   ```
3. **投资评估和监控**

   ```
   Agent的质量很大程度上取决于：
   - 工具的质量
   - 测试的覆盖度
   - 监控的完善性
   ```

***

## 🚨 关键警告

### ⚠️ 上下文管理至关重要

**问题**：

```
长时间运行的Agent会面临：
- 上下文窗口耗尽
- 无关信息污染
- 性能下降
```

**解决**：

* 使用Compaction功能
* 合理使用Subagents进行上下文隔离
* 定期清理不需要的上下文

### ⚠️ 工具设计直接影响Agent能力

**问题**：

```
糟糕的工具设计导致：
- Agent频繁失败
- 资源浪费
- 用户体验差
```

**解决**：

* 参考"Writing effective tools"文章
* 站在Agent的角度设计工具
* 持续迭代和优化

### ⚠️ 测试是成功的关键

**问题**：

```
没有充分测试的Agent：
- 在生产环境中频繁失败
- 难以诊断问题
- 用户信任度低
```

**解决**：

* 构建代表性测试集
* 包含边缘情况
* 持续监控和改进

***

## 📊 价值评估

| 维度       | 评分    | 说明                       |
| -------- | ----- | ------------------------ |
| **理论深度** | ⭐⭐⭐⭐⭐ | 提出了完整的Agent工作循环理论        |
| **实践指导** | ⭐⭐⭐⭐⭐ | 提供了大量可操作的实践建议            |
| **技术创新** | ⭐⭐⭐⭐☆ | Claude Agent SDK是工具层面的创新 |
| **长期价值** | ⭐⭐⭐⭐⭐ | 定义了Agent开发的标准范式          |

***

## 🔮 未来展望

### 可能的发展方向

1. **更强大的上下文管理**
   * 自动的上下文优化
   * 更智能的信息检索
   * 跨会话的记忆持久化
2. **更丰富的MCP生态**
   * 更多第三方MCP Server
   * 标准化的工具接口
   * 企业级的安全和权限管理
3. **Multi-Agent编排的成熟**
   * 标准化的Agent通信协议
   * 更强大的协调机制
   * 分布式Agent系统
4. **Agent开发的工程化**
   * Agent开发的IDE支持
   * Agent的CI/CD流程
   * Agent的可观测性工具

***

## 📚 延伸阅读

### 在本知识库中

1. **上下文工程系列**
   * `Effective context engineering for AI agents.md`
   * `MCP与Agent上下文切换机制分析报告.md`
2. **工具设计系列**
   * `Writing effective tools for agents.md`
   * `Desktop Extensions.md`
3. **实战案例系列**
   * `How we built our multi-agent research system.md`
   * `Claude Code Best Practices.md`

### 外部资源

* **Claude Agent SDK文档**：<https://docs.claude.com/en/api/agent-sdk/overview>
* **MCP协议**：<https://modelcontextprotocol.io/>
* **MCP Server生态**：<https://github.com/modelcontextprotocol/servers>

***

## 💭 个人思考与启发

### 思考1：从工具到生态

**观察**：

```
Claude Code → Claude Agent SDK
编码工具 → 通用Agent框架
```

这个转变揭示了一个重要趋势：**专用工具向通用平台的演进**。

**启发**： 在构建AI产品时，考虑其可扩展性和通用性。一个好的设计应该能够轻松扩展到新的场景。

### 思考2：Agent = 计算机使用能力

**观察**：

```
给Claude一台计算机 = 解锁无限可能

这个简单的原则背后是深刻的洞察：
AI不需要特殊的接口，只需要人类使用的工具。
```

**启发**： 与其为AI设计特殊的接口，不如让AI使用现有的工具和接口。这降低了集成成本，提高了灵活性。

### 思考3：反馈循环的重要性

**观察**：

```
Gather Context → Take Action → Verify Work → Repeat

这个循环模式不是Agent特有的，而是智能行为的通用模式。
```

**启发**： 无论构建什么样的AI系统，都应该设计**验证和反馈机制**。没有反馈的系统很难改进。

***

**最后的话**：

这篇文章标志着Anthropic在Agent开发方面的一次重要战略升级。从Claude Code到Claude Agent SDK，不仅是名称的改变，更是**从单一场景到通用框架**的范式转变。

对于开发者而言，这是一个信号：**Agent不再是实验性的功能，而是生产就绪的核心能力**。

对于行业而言，这可能是**Agent开发标准化的开始**。就像React定义了前端开发，Django定义了Web开发，Claude Agent SDK可能会定义Agent开发。

**值得持续关注！** 🚀