tools-only 第九课：使用 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 项目目录结构
根据视频演示，推荐的目录结构如下：
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 依赖：
# 初始化 uv 项目
uv init
# 安装 Claude Agent SDK 及相关工具
uv add claude-agent-sdk python-dotenv asyncio
3. 代码实现核心逻辑 (agent.py Anatomy)
agent.py 是整个系统的控制中心。以下是基于视频脚本的代码构建步骤解析：
第一步：导入与辅助函数
视频中使用了 display_message 来美化终端输出，这对于调试智能体的思考过程非常重要。
import asyncio
import os
from dotenv import load_dotenv
from claude_agent_sdk.utils import display_message # 用于格式化输出
# ... 导入其他依赖
第二步：配置工具与权限 (The Tools)
SDK 默认是只读且安全的。为了让智能体能写代码和上网，必须显式授权。
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 服务器，赋予智能体操作外部笔记系统的能力。
# 定义 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 来调度子智能体。
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 框架复用，无需修改代码。