2937 9skills With The Claude Agent Sdkclaude Agent Sdk 中的技能 D245e7f7

# 第九课：使用 Claude Agent SDK 构建实战级研究智能体

本节课我们将脱离网页版 Claude 和命令行界面 (CLI)，深入讲解如何使用 **Claude Agent SDK** 以编程方式构建复杂的智能体应用。

我们将从零开始构建一个 **通用研究智能体 (Research Agent)**。该智能体模拟了一个高效的工程团队：由一个“指挥官”利用标准流程 (Skills) 制定计划，并行调度三个“专家” (Sub-agents) 进行分工协作，最终通过 MCP 将成果交付到外部系统 (Notion)。

---

## 1. 核心架构：指挥官与专家团队 (The Architecture)

我们使用 SDK 构建的系统架构可以映射为传统的企业组织结构：
| 架构层级 | 概念隐喻 (Metaphor) | 代码组件 (SDK Component) | 本案具体实现 (Implementation) |
| :--- | :--- | :--- | :--- |
| **The Brain** | **指挥官 / 编排者** | `Main Agent` + `TaskTool` | 负责理解需求，加载技能制定计划，分派任务，最后合成报告。 |
| **The Arms** | **专家 / 执行者** | `AgentDefinition` (Sub-agents) | **Docs Researcher** (查文档)<br>**Repo Analyzer** (跑代码)<br>**Web Researcher** (搜视频) |
| **Process** | **标准作业程序 (SOP)** | `SkillTool` | `learning-a-tool`: 一个定义了“如何学习新工具”的标准流程技能。 |
| **Connectivity** | **外部连接器** | `MCP Server` | **Notion MCP**: 用于将生成的 Markdown 报告写入云端 Notion 页面。 |

![描述](./images/9.1.png)

> **关键区别**：在本案例中，**技能 (Skill) 是专门给主智能体用的**，作为其规划的指导手册；而**子智能体 (Sub-agents)** 则是去执行具体脏活累活的。

---

## 2. 环境搭建与工程结构 (Setup & Structure)

为了让 SDK 正确加载技能和代理定义，文件结构必须遵循特定规范。

### 2.1 项目目录结构
根据视频演示，推荐的目录结构如下：

```text
research-agent/
├── .env                  # 🔑 存放 ANTHROPIC_API_KEY, NOTION_API_TOKEN
├── agent.py              # 🧠 主程序入口 (The Brain)
├── agents/               # 🤖 子智能体定义 (The Arms)
│   ├── docs_researcher.md
│   ├── repo_analyzer.md
│   └── web_researcher.md
└── .claude/              # 📚 技能库 (Infrastructure)
    └── skills/           # ⚠️ 必须命名为 'skills' (复数)
        └── learning-a-tool/
            ├── SKILL.md  # 技能入口文件
            └── progressive_learning.md # 渐进式加载的详细内容
```

### 2.2 初始化与依赖安装
在终端中执行以下命令初始化项目并安装 Python 依赖：

```bash
# 初始化 uv 项目
uv init

# 安装 Claude Agent SDK 及相关工具
uv add claude-agent-sdk python-dotenv asyncio
```

---

## 3. 代码实现核心逻辑 (`agent.py` Anatomy)

`agent.py` 是整个系统的控制中心。以下是基于视频脚本的代码构建步骤解析：

### 第一步：导入与辅助函数
视频中使用了 `display_message` 来美化终端输出，这对于调试智能体的思考过程非常重要。

```python
import asyncio
import os
from dotenv import load_dotenv
from claude_agent_sdk.utils import display_message # 用于格式化输出
# ... 导入其他依赖
```

### 第二步：配置工具与权限 (The Tools)
SDK 默认是**只读且安全**的。为了让智能体能写代码和上网，必须显式授权。

```python
from claude_agent_sdk.tools import Bash, Write, WebSearch, WebFetch

# 显式允许高权限工具
allowed_tools = [
    Write,      # 允许写文件 (生成 README.md 等)
    Bash,       # 允许执行 Shell 命令 (如 git clone)
    WebSearch,  # 允许联网搜索
    WebFetch    # 允许抓取网页内容
]
```

### 第三步：集成 MCP (Notion)
通过代码连接 Notion MCP 服务器，赋予智能体操作外部笔记系统的能力。

```python
# 定义 MCP Server 配置
mcp_servers = {
    "notion": {
        "command": "uv",
        "args": ["run", "mcp-server-notion"], # 运行 Notion MCP
        "env": {"NOTION_API_TOKEN": os.getenv("NOTION_API_TOKEN")}
    }
}

# ⚠️ 关键：必须将 MCP 工具加入允许列表
# 使用通配符允许所有 Notion 相关操作
allowed_tools.append("mcp_notion_*")
```

### 第四步：加载技能与任务调度 (Skills & Orchestration)
这是让“大脑”能运作的关键。必须添加 `SkillTool` 来读取技能，添加 `TaskTool` 来调度子智能体。

```python
from claude_agent_sdk.tools import SkillTool, TaskTool

# 1. 配置 SkillTool
# setting_sources=["project"] 告诉 SDK 在当前项目的 .claude/skills 中查找
skill_tool = SkillTool(setting_sources=["project", "user"])

# 2. 配置 TaskTool (需要先加载子智能体定义)
# 加载 prompts/defs ... (此处省略加载过程)
task_tool = TaskTool(agents=sub_agent_definitions) 

# 将它们加入工具集
allowed_tools.extend([skill_tool, task_tool])
```

---

## 4. 角色定义与分工 (Defining Roles)

在代码中，我们需要通过 `AgentDefinition` 类来定义每个子智能体的职责边界。

| 角色 (Role) | 核心职责 | 关键工具配置 (Key Tools) |
| :--- | :--- | :--- |
| **Main Agent** | **编排与合成**。加载技能制定计划，分派任务给子智能体，汇总结果并写入 Notion。 | `TaskTool`, `SkillTool`, `mcp_notion_*` |
| **Docs Researcher** | **文档研究**。查找和阅读官方文档。 | `WebSearch`, `WebFetch` |
| **Repo Analyzer** | **代码分析**。克隆 GitHub 仓库，分析文件结构和代码逻辑。 | **`Bash`** (执行 git clone), `Read`, `Grep` |
| **Web Researcher** | **广泛搜索**。查找教程、视频（YouTube）和社区讨论。 | `WebSearch`, `WebFetch` |

> **注意**：子智能体的 `allowed_tools` 是独立的。例如，只有 Repo Analyzer 需要 `Bash` 权限，其他研究员不需要，这体现了**最小权限原则**。

---

## 5. 工作流演示：研究 "MinerU" (Execution Flow)

课程演示了从零开始研究开源 PDF 提取工具 "MinerU" 的完整生命周期。这个过程展示了如何处理非确定性任务。

### 阶段 1：规划 (Planning) & 渐进式披露
*   **用户指令**：*"Create a learning guide for MinerU, show me the plan first."*
*   **动作**：主智能体加载 `learning-a-tool` 技能。
*   **技术细节 (Progressive Disclosure)**：SDK 最初只加载技能的名称。当技能被触发时，它加载底层的 `SKILL.md`，并在需要时进一步加载引用的 `progressive_learning.md`。这保护了上下文窗口，避免一次性加载过多 Token。

### 阶段 2：并行执行 (Parallel Execution)
*   **动作**：主智能体根据计划，使用 `TaskTool` **同时调度**三个子智能体。
*   **并行处理**：
    *   *Docs Researcher* -> 阅读官方文档。
    *   *Repo Analyzer* -> 执行 `git clone` 拉取代码并分析结构。
    *   *Web Researcher* -> 在 YouTube 搜索视频教程。
*   **优势**：互不阻塞，极大提高了复杂任务的执行效率。

### 阶段 3：合成 (Synthesis)
*   **动作**：子智能体返回结果后，主智能体在本地文件系统生成标准化的目录结构：
    *   `README.md`: 包含学习路径和时间预估。
    *   `resources.md`: 整理好的链接和参考文献。
    *   `examples/`: 生成 Hello World 代码示例。

### 阶段 4：交付 (Delivery via MCP)
*   **用户指令**：*"Write the resources file to Notion."*
*   **动作**：主智能体调用 Notion MCP 工具 (`mcp_notion_append_block_children`)。
*   **结果**：它读取本地的 `resources.md`，将其转换为 Notion 的 **Rich Blocks**（富文本块），并自动写入到云端的 Notion 页面中。

---

## 6. 关键启示与安全最佳实践 (Key Takeaways)

### 6.1 SDK vs Claude Code (CLI)
开发者常问：*“我应该用 Claude Code 命令行工具，还是自己写 Python SDK？”*

| 维度 | Claude Code (CLI) | Claude Agent SDK (Python) |
| :--- | :--- | :--- |
| **定位** | 交互式工具，用于辅助编程和一次性任务。 | **编程框架**，用于构建可扩展的 AI 应用程序。 |
| **控制力** | 由系统接管大部分决策。 | 开发者可精细控制 **System Prompt**、**工具集** 和 **错误处理逻辑**。 |
| **集成性** | 独立运行。 | 可集成到现有的后端服务或产品中。 |

### 6.2 安全性警告 (Security Note)
⚠️ **Human-in-the-loop (人机回环)**
在课程的演示代码中，为了流程顺畅，我们直接允许了 `Bash` 和 `Write` 的自动执行。
*   **生产环境风险**：Agent 可能会执行危险命令（如删除文件）或覆盖重要数据。
*   **最佳实践**：在构建生产级应用时，必须实现**拦截机制**。当模型请求使用高风险工具时，暂停执行并向用户展示确认框（Permission Request），用户批准后方可继续。

### 6.3 技能的可移植性 (Portability)
我们在 `.claude/skills` 中编写的技能文件是符合 **Open Standard** 的。这意味着你在 Python SDK 中编写的技能，可以直接拖入 Claude Desktop 使用，也可以被其他支持该标准的 Agent 框架复用，无需修改代码。

[返回目录](./README.md)