第九课：使用 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 (查文档)
Repo Analyzer (跑代码)
Web Researcher (搜视频)
Process 标准作业程序 (SOP) SkillTool learning-a-tool: 一个定义了“如何学习新工具”的标准流程技能。
Connectivity 外部连接器 MCP Server Notion MCP: 用于将生成的 Markdown 报告写入云端 Notion 页面。

描述

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

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

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

2.1 项目目录结构

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

1
2
3
4
5
6
7
8
9
10
11
12
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 依赖：

1
2
3
4
5
# 初始化 uv 项目
uv init

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

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

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

第一步：导入与辅助函数

视频中使用了 display_message 来美化终端输出，这对于调试智能体的思考过程非常重要。

1
2
3
4
5
import asyncio
import os
from dotenv import load_dotenv
from claude_agent_sdk.utils import display_message # 用于格式化输出
# ... 导入其他依赖

第二步：配置工具与权限 (The Tools)

SDK 默认是只读且安全的。为了让智能体能写代码和上网，必须显式授权。

1
2
3
4
5
6
7
8
9
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 服务器，赋予智能体操作外部笔记系统的能力。

1
2
3
4
5
6
7
8
9
10
11
12
# 定义 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 来调度子智能体。

1
2
3
4
5
6
7
8
9
10
11
12
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 框架复用，无需修改代码。

返回目录