Skills with the Claude Agent SDK

本篇内容为转载因为觉得datawhale这节课内容笔记整理得特别好于是基本没有做什么内化改动就转载发表作为系列笔记了原作者如下原网页链接在此——第九课使用 Claude Agent SDK 构建实战级研究智能体。查昊南负责人邓一纯内容核查人大部分资料源自Datawhale社区datawhalechina/agent-skills-with-anthropic 项目教程全篇如无特殊说明则默认资料来源上述教程具体参考链接见文末【系列博客】Introduction to Agent Skills一Introduction to Agent Skills 二Skill with the Claude APISkill with Claude CodeSkills with the Claude Agent SDK目录核心架构指挥官与专家团队环境搭建与工程结构项目目录结构初始化与依赖安装代码实现逻辑 (agent.py 解析)Step 1. 导入与辅助函数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 TakeawaysSDK 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 AgentTaskTool负责理解需求加载技能制定计划分派任务最后合成报告。The Arms专家 / 执行者AgentDefinition(Sub-agents)Docs Researcher(查文档)Repo Analyzer(跑代码)Web Researcher(搜视频)Process标准作业程序 (SOP)SkillToollearning-a-tool: 一个定义了“如何学习新工具”的标准流程技能。Connectivity外部连接器MCP ServerNotion 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(agentssub_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,WebFetchRepo Analyzer代码分析。克隆 GitHub 仓库分析文件结构和代码逻辑。Bash(执行 git clone),Read,GrepWeb 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 TakeawaysSDK vs Claude Code (CLI)开发者常问“我应该用 Claude Code 命令行工具还是自己写 Python SDK”维度Claude Code (CLI)Claude Agent SDK (Python)定位交互式工具用于辅助编程和一次性任务。编程框架用于构建可扩展的 AI 应用程序。控制力由系统接管大部分决策。开发者可精细控制System Prompt、工具集和错误处理逻辑。集成性独立运行。可集成到现有的后端服务或产品中。安全性警告 (Security Note)⚠️Human-in-the-loop (人机回环)在课程的演示代码中为了流程顺畅我们直接允许了Bash和Write的自动执行。生产环境风险Agent 可能会执行危险命令如删除文件或覆盖重要数据。最佳实践在构建生产级应用时必须实现拦截机制。当模型请求使用高风险工具时暂停执行并向用户展示确认框Permission Request用户批准后方可继续。技能的可移植性 (Portability)在.claude/skills中编写的技能文件是符合Open Standard的。这意味着我们在 Python SDK 中编写的技能可以直接拖入 Claude Desktop 使用也可以被其他支持该标准的 Agent 框架复用无需修改代码。【教程地址】https://github.com/datawhalechina/agent-skills-with-anthropic【课程列表链接】https://www.datawhale.cn/activityGroup/16?sourceId1809【视频教程地址】 吴恩达 DeepLearning.AI - agent-skills-with-anthropic【官网解读教程】sc-agent-skills-files