Skills with the Claude Agent SDK

该智能体模拟了一个高效的工程团队：由一个“指挥官”利用标准流程 (Skills) 制定计划，并行调度三个“专家” (Sub-agents) 进行分工协作，最终通过 MCP 将成果交付到外部系统 (Notion)。这意味着我们在 Python SDK 中编写的技能，可以直接拖入 Claude Desktop 使用，也可以被其他支持该标准的 Agent 框架复用，无需修改代码。通过代码连接 Notio

m0_74186864

75人浏览 · 2026-03-28 10:57:34

m0_74186864 · 2026-03-28 10:57:34 发布

本篇内容为转载！！！ 因为觉得datawhale这节课内容笔记整理得特别好，于是基本没有做什么内化改动就转载发表作为系列笔记了，原作者如下，原网页链接在此——第九课：使用 Claude Agent SDK 构建实战级研究智能体。

查昊南（负责人）邓一纯（内容核查人）

大部分资料源自Datawhale社区 datawhalechina/agent-skills-with-anthropic 项目教程

全篇如无特殊说明，则默认资料来源上述教程，具体参考链接见文末

【系列博客】：

Introduction to Agent Skills（一）

Introduction to Agent Skills （二）

Skill with the Claude API

Skill with Claude Code

Skills with the Claude Agent SDK

Step 2. 配置工具与权限 (The Tools)

Step 3. 集成 MCP (Notion)

Step 4. 加载技能与任务调度

角色定义与分工 (Defining Roles)

工作流演示："MinerU"

阶段 1：规划 (Planning) & 渐进式披露

阶段 2：并行执行 (Parallel Execution)

阶段 3：合成 (Synthesis)

阶段 4：交付 (Delivery via MCP)Key Takeaways

SDK vs Claude Code (CLI)

安全性警告 (Security Note)

技能的可移植性 (Portability)

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

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

核心架构：指挥官与专家团队

使用 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) 则是去执行具体脏活累活的。

环境搭建与工程结构

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

项目目录结构

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

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 # 渐进式加载的详细内容

初始化与依赖安装

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

# 初始化 uv 项目
uv init

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

代码实现逻辑 (`agent.py` 解析)

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

Step 1. 导入与辅助函数

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

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

Step 2. 配置工具与权限 (The Tools)

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

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

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

Step 3. 集成 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_*")

Step 4. 加载技能与任务调度

这是让“大脑”能运作的关键。必须添加 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])

角色定义与分工 (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 权限，其他研究员不需要，这体现了最小权限原则。

工作流演示："MinerU"

课程演示了从零开始研究开源 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 页面中。

Key Takeaways

SDK vs Claude Code (CLI)

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

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