收藏这份Claude Agent SDK内置工具指南：18+工具体系解析，小白也能轻松掌握大模型开发新范式！

本文全面解析Anthropic最新Claude Agent SDK的18+内置工具体系，涵盖文件操作、命令执行、搜索、Web功能等核心场景。重点介绍了Task工具的子代理编排能力、TodoWrite工具的任务管理功能，以及WebSearch、Plan Mode、Skill等特色工具。同时详解了工具权限控制、安全模型和MCP生态系统，帮助开发者掌握AI Agent开发新范式。文章内容适合小白和程序员学习大模型开发。

引言

如果你正在关注 AI Agent 开发领域，一定听说过 Anthropic 推出的 Claude Agent SDK。这个 SDK 让开发者能够以编程方式调用 Claude 的能力，构建自己的 AI Agent 应用。

值得注意的是，Anthropic 在 2025 年将 SDK 从 claude-code-sdk 更名为 claude-agent-sdk，这一变化反映了该 SDK 从最初专注于代码生成工具，演进为支持更广泛应用场景的通用 AI Agent 平台。正如官方所述：“这个 SDK 是驱动 Claude Code 的同一引擎，现在作为库暴露出来，让你可以将其指向任何你想解决的问题。”

本文将带你全面了解 Claude Agent SDK 的内置工具体系，特别是 Task 工具的子代理编排能力，以及 TodoWrite 工具如何配合 Claude Code 产品层面的 Tasks 系统实现任务管理，帮助你更好地理解和使用这个强大的 SDK。

---

一、Claude Agent SDK 内置工具全景图

Claude Agent SDK 提供了 18+ 个内置工具，覆盖了 AI Agent 开发的各个核心场景。我们按功能类别来逐一介绍：

1. 文件操作类

工具名	功能说明
Read	读取文件内容，支持指定行数范围，可读取代码、配置、图片、PDF 等多种格式
Write	写入文件内容，会覆盖已存在的文件
Edit	精确的字符串替换编辑，适合对现有文件进行局部修改
NotebookEdit	专门用于编辑 Jupyter Notebook(.ipynb 文件）的单元格

使用场景：代码生成、配置文件修改、文档处理等。

2. 命令执行类

工具名	功能说明
Bash	执行 bash 命令，支持超时设置和后台运行
BashOutput	获取后台运行的 bash 命令输出
KillBash	终止正在运行的后台 bash 进程

使用场景：运行测试、执行构建、Git 操作、系统管理等。

3. 文件搜索类

工具名	功能说明
Glob	基于 glob 模式的快速文件匹配，如 /*.ts
Grep	基于正则表达式的文件内容搜索，底层使用 ripgrep

使用场景：代码搜索、文件定位、模式匹配等。

4. Web 功能类

工具名	功能说明
WebSearch	网络搜索，获取最新信息
WebFetch	抓取指定 URL 的内容并进行分析

使用场景：获取最新文档、查询 API 信息、研究调研等。

深度解析：WebSearch 的底层实现机制

你可能会好奇：Claude 模型本身并不具备联网能力，WebSearch 是如何实现的？

答案是：WebSearch 是 Anthropic 提供的一个「服务端工具」(Server Tool)，而非模型内置能力。

工作原理如下：

1. 1. 当你在 API 请求中添加 web_search 工具时，Claude 会根据用户提示决定是否需要搜索

2. 2. 如果需要搜索，Claude 生成搜索查询，API 服务端执行实际的搜索操作

3. 3. 搜索结果返回给 Claude, Claude 基于结果生成带引用的回答

4. 4. 这个过程可能在单次请求中重复多次

关键点：

• 搜索由 Anthropic 服务端执行，不是模型自己联网
• 支持域名过滤（allowed_domains / blocked_domains)
• 支持地理位置本地化（user_location)
• 自动生成引用，cited_text 字段包含引用内容
• 定价：$10 / 1000 次搜索，加上标准 token 费用

这种设计让 Claude 能够获取实时信息，同时保持了模型本身的安全性和可控性。

5. 用户交互类

工具名	功能说明
AskUserQuestion	向用户提问，支持多选项选择，实现规格驱动开发

使用场景：需求澄清、进度展示、用户确认等。

AskUserQuestion：规格驱动开发的关键

AskUserQuestion 工具正在成为 Claude Code 中最强大但被低估的功能之一。它颠覆了传统的开发流程：

传统流程：你给 AI 一个模糊需求 → AI 猜测并实现 → 你发现不对 → 反复修改

规格驱动流程： AI 先通过 AskUserQuestion 询问所有关键决策 → 生成详细规格文档 → 基于规格精确实现

例如，Claude 会问：“这个 API 应该快速失败还是带退避重试？” 在写任何代码之前，所有权衡都变得明确。结果是：代码第一次就符合你的意图。

6. 任务管理类

工具名	功能说明
TodoWrite	创建和管理结构化任务列表，跟踪进度

使用场景：复杂任务分解、进度可视化、任务状态追踪等。

TodoWrite：让 AI 的工作计划可见

TodoWrite 是 Claude Agent SDK 中最容易被忽视但极其重要的工具。它不是简单的待办清单，而是 Claude 与用户沟通工作计划的核心机制。

工作原理：

当你给 Claude 一个复杂任务时，它会首先使用 TodoWrite 创建一个结构化的任务列表：

TodoWrite({ todos: [ { content: "分析现有代码结构", status: "in_progress", activeForm: "正在使用 Grep 搜索相关文件..." }, { content: "设计新功能架构", status: "pending" }, { content: "实现核心逻辑", status: "pending" } ]})

三种状态：

• pending：待处理
• in_progress：正在处理（会显示 activeForm 字段的详细进度）
• completed：已完成

为什么重要：

1. 1. 透明度：你能实时看到 Claude 的工作计划和当前进度

2. 2. 早期发现问题：如果 Claude 误解了需求，你能在代码编写前就发现

3. 3. 中途调整：可以根据 todo 列表调整优先级或方向

4. 4. 复杂任务管理：对于多步骤任务，todo 列表确保不会遗漏步骤

7. 代理编排类

工具名	功能说明
Task	启动子代理执行复杂任务，支持后台运行
TaskOutput	获取后台任务的执行结果和状态
TaskStop	停止正在运行的后台任务

使用场景：复杂任务分解、多代理协作、专业化处理、并行执行等。

Task 工具的后台执行模式

Task 工具支持两种执行模式：

前台执行（默认）：主代理等待子代理完成，适合需要立即使用结果的场景

Task({ subagent_type: "security-reviewer", prompt: "审查这个文件的安全问题", run_in_background: false // 默认值})

后台执行：子代理在后台运行，主代理继续处理其他任务

// 启动后台任务Task({ subagent_type: "test-runner", prompt: "运行完整测试套件", run_in_background: true})// 主代理继续工作...// 稍后检查结果TaskOutput({ task_id: "a42a16e", block: true // 等待任务完成})// 或者停止任务TaskStop({ task_id: "a42a16e"})

最佳实践：

• 长时间运行的任务（测试、构建）应使用后台模式
• 使用 TaskOutput 而非 Read 或 Bash tail 来检查后台任务状态
• 后台任务应将结果写入文件，避免通过 TaskOutput 传输大量数据

8. 计划模式类

工具名	功能说明
EnterPlanMode	进入计划模式，只研究不执行
ExitPlanMode	退出计划模式，提交方案供用户审批

使用场景：复杂变更前的规划、架构设计、代码审查等。

Plan Mode：思考与执行的分离

Plan Mode 是 Claude Code 中最强大的工作流模式之一，它将"研究分析"与"实际执行"完全分离。

工作流程：

1. 1. 进入计划模式： Claude 调用 EnterPlanMode 工具

2. 2. 只读研究：在此模式下，Claude 只能使用只读工具（Read、Grep、Glob、WebSearch 等）

3. 3. 生成计划： Claude 将研究结果写入计划文件（通常是 Markdown 格式）

4. 4. 请求审批：调用 ExitPlanMode 工具，向用户展示计划

5. 5. 用户决策：用户可以批准、修改或拒绝计划

6. 6. 执行阶段：批准后，Claude 根据计划文件执行实际操作

为什么需要 Plan Mode:

// 传统模式的问题"重构这个 10,000 行的代码库"→ Claude 立即开始修改文件→ 你发现方向不对,但已经改了 50 个文件→ 回滚困难// Plan Mode 的优势"重构这个 10,000 行的代码库"→ Claude 进入 Plan Mode→ 分析代码结构、依赖关系、测试覆盖率→ 生成详细的重构计划(分 5 个阶段,每阶段的文件列表和修改策略)→ 你审查计划,发现第 3 阶段有风险,要求调整→ Claude 更新计划→ 你批准后,Claude 开始执行→ 每个阶段都可以验证,风险可控

Plan Mode 的性能优势：

Plan Mode 使用 Opus 4.5 时特别高效：

• 只读操作不会触发大量工具调用
• 计划文件紧凑，token 使用量少
• 用户可以在执行前编辑计划文件，无需重新生成

9. 技能调用类

工具名	功能说明
Skill	调用预定义的技能（Skills）和斜杠命令

使用场景：复用常见工作流、调用专业知识、执行标准化操作等。

Skill 工具：可复用的工作流模板

Skill 工具是 Claude Agent SDK 的元工具（meta-tool），它允许 Claude 动态加载和执行预定义的工作流。

什么是 Skills:

Skills 是存储在 .claude/skills/ 目录中的 Markdown 文件，包含：

• 专业知识（如特定框架的最佳实践）
• 工作流模板（如代码审查流程）
• 工具组合模式（如"搜索→分析→修复"的标准流程）

Skills vs 斜杠命令：

在 Claude Code 2.1.3 版本后，Skills 和斜杠命令已经合并，使用相同的定义格式：

---name: security-reviewdescription: 全面的安全审查流程allowed-tools: Read, Grep, Glob, WebFetch---# 安全审查流程1. 使用 Grep 搜索常见漏洞模式: - SQL 注入:`SELECT.*/$` - XSS:`innerHTML.*=` - 硬编码密钥:`API_KEY|SECRET|PASSWORD`2. 使用 Read 读取可疑文件3. 使用 WebFetch 获取最新的安全最佳实践4. 生成审查报告

两种调用方式：

1. 1. 用户手动调用：/security-review

2. 2. Claude 自动调用：当用户说"审查代码安全性"时，Claude 会自动使用 Skill 工具调用 security-review

Skills 的优势：

• 上下文高效： Skills 默认不加载到上下文，只有在需要时才动态加载
• 知识封装：可以将大量专业知识（如完整的 API 文档）封装在 Skill 中
• 团队共享：团队可以共享标准化的工作流
• 版本控制： Skills 文件可以纳入 Git 管理

10. 工具发现类

工具名	功能说明
ToolSearch	动态搜索和加载延迟加载的工具

使用场景：大型工具集管理、MCP 服务器工具发现、按需加载工具等。

ToolSearch：解决上下文污染的利器

当你的 Agent 可用工具超过 50 个时，将所有工具定义加载到上下文会导致严重的 token 浪费。ToolSearch 工具解决了这个问题。

问题场景：

// 传统方式:加载所有工具const agent = new Agent({ tools: [ tool1, tool2, tool3, ..., tool50 // 所有工具定义占用 20,000 tokens ]})// 但 Claude 可能只需要用到其中 3 个工具

ToolSearch 方式：

// 延迟加载工具const agent = new Agent({ tools: [ { name: "get_user", defer_loading: true, description: "获取用户信息" }, { name: "update_user", defer_loading: true, description: "更新用户信息" }, // ... 其他 48 个工具 ]})// Claude 的工作流程:// 1. 用户:"获取用户 123 的信息"// 2. Claude 调用 ToolSearch("获取用户")// 3. ToolSearch 返回匹配的工具:get_user// 4. 系统加载 get_user 的完整定义到上下文// 5. Claude 调用 get_user(user_id=123)

最佳实践：

• 保留常用工具：将 3-5 个最常用的工具设为立即加载
• 优化描述：延迟加载工具的 description 字段是搜索的关键，要准确且包含关键词
• MCP 集成： ToolSearch 特别适合 MCP 服务器，因为 MCP 服务器通常提供大量工具

性能提升：

Anthropic 的测试显示，使用 ToolSearch 后：

• 上下文 token 减少 60-80%
• 响应速度提升 30-50%
• 成本降低 50-70%

11. MCP 资源类

工具名	功能说明
ListMcpResources	列出可用的 MCP 资源
ReadMcpResource	读取指定的 MCP 资源内容

使用场景：与外部服务集成、扩展 Agent 能力等。

---

二、澄清：Task 工具、TodoWrite 工具与 Tasks 系统

这是最容易混淆的概念，让我们明确区分：

三个不同层面的“任务”概念

1. Task 工具（子代理编排）

• 层面： SDK 工具层
• 功能：启动子代理（subagent）来处理复杂任务
• 类比：项目经理将任务委派给专家团队成员
• 状态：一直存在，是 SDK 的核心工具

Task({ subagent_type: "security-reviewer", prompt: "审查这个文件的安全问题"})

2. TodoWrite 工具（任务列表管理）

• 层面： SDK 工具层
• 功能：创建和管理结构化的任务列表，让用户看到 AI 的工作计划
• 类比：项目看板，显示所有待办事项和进度
• 状态：一直存在，是 SDK 的核心工具

TodoWrite({ todos: [ { content: "分析代码", status: "completed" }, { content: "设计方案", status: "in_progress" }, { content: "实现功能", status: "pending" } ]})

3. Tasks 系统（Claude Code 产品功能）

• 层面： Claude Code 产品层
• 功能：持久化的任务管理系统，支持跨会话、依赖追踪、层级结构
• 类比： Jira/Linear 这样的项目管理系统
• 状态：2025 年 1 月引入，取代了旧版的临时 Todos 机制

它们之间的关系

┌─────────────────────────────────────────────────────────┐│ Claude Code 产品层 ││ ││ ┌─────────────────────────────────────────────────┐ ││ │ Tasks 系统(持久化任务管理) │ ││ │ - 存储在 ~/.claude/tasks │ ││ │ - 支持依赖关系、层级结构 │ ││ │ - 跨会话保留 │ ││ └─────────────────────────────────────────────────┘ ││ ↑ ││ │ 底层使用 ││ ↓ │└─────────────────────────────────────────────────────────┘┌─────────────────────────────────────────────────────────┐│ Claude Agent SDK 工具层 ││ ││ ┌──────────────────┐ ┌──────────────────┐ ││ │ Task 工具 │ │ TodoWrite 工具 │ ││ │ (子代理编排) │ │ (任务列表管理) │ ││ │ │ │ │ ││ │ - 启动子代理 │ │ - 创建 todo 列表 │ ││ │ - 并行执行 │ │ - 更新任务状态 │ ││ │ - 上下文隔离 │ │ - 进度可视化 │ ││ └──────────────────┘ └──────────────────┘ ││ │└─────────────────────────────────────────────────────────┘

2025 年 1 月的更新到底是什么？

不是： Task 工具取代了 TodoWrite 工具（它们都继续存在）

而是： Claude Code 产品的 Tasks 持久化系统升级了原有的临时 Todos 机制

旧版 Todos 机制的问题：

• 存储在内存中，会话结束就消失
• 不支持任务间依赖关系
• 上下文压缩后会丢失
• 子代理无法访问主代理的任务列表

新版 Tasks 系统的改进：

• 持久化存储在 ~/.claude/tasks
• 支持任务依赖和层级结构
• 跨会话保留
• 子代理可以访问和更新任务
• AI 可以从 PRD 自动生成任务树

---

三、Task 工具：多代理编排的核心

什么是 Task 工具？

Task 是 Claude Agent SDK 中最重要的新特性之一。它不是一个简单的工具调用，而是一个子代理编排器——能够启动独立的子代理（Subagent）来处理特定任务。

你可以把它理解为：主代理是项目经理，Task 工具让它能够将任务分配给不同的专家团队成员。

Task 工具的核心参数

interface AgentInput { description: string; // 任务简短描述(3-5 词) prompt: string; // 子代理要执行的具体任务 subagent_type: string; // 子代理类型(对应配置中的 key) model?: string; // 可选:指定使用的模型 resume?: string; // 可选:恢复之前的执行 run_in_background?: boolean; // 可选:后台运行 max_turns?: number; // 可选:最大对话轮次}

如何定义子代理？

子代理通过 AgentDefinition 配置定义。以下是一个实际的代码审查场景：

import { query, AgentDefinition } from "@anthropic-ai/claude-agent-sdk";async function comprehensiveReview(directory: string) { for await (const message of query({ prompt: `对 ${directory} 执行全面的代码审查。使用 security-reviewer 检查安全问题,使用 test-analyzer 分析测试覆盖率。`, options: { model: "opus", allowedTools: ["Read", "Glob", "Grep", "Task"], // Task 启用子代理 permissionMode: "bypassPermissions", maxTurns: 250, agents: { "security-reviewer": { description: "安全专家,用于漏洞检测", prompt: `你是安全专家。分析:- SQL 注入风险- XSS 漏洞- 认证/授权问题- 敏感数据暴露`, tools: ["Read", "Grep", "Glob"], // 只读工具,确保安全 model: "opus" // 安全审查用强模型 } as AgentDefinition, "test-analyzer": { description: "测试专家,用于覆盖率分析", prompt: `你是测试专家。分析:- 测试覆盖率缺口- 缺失的边界情况- 测试质量和可靠性- 额外测试建议`, tools: ["Read", "Grep", "Glob"], model: "haiku" // 简单分析用快速模型 } as AgentDefinition } } })) { if (message.type === "assistant") { for (const block of message.message.content) { if ("text" in block) { console.log(block.text); } else if ("name" in block && block.name === "Task") { console.log(`🤖 委托给: ${(block.input as any).subagent_type}`); } } } }}comprehensiveReview("./src");

子代理的关键优势

1. 上下文隔离

每个子代理维护自己的内存；只有关键结果返回给主代理。这防止了上下文窗口爆炸。

2. 并行化

可以并发运行多个搜索或分析任务。例如：

from claude_agent_sdk import query, ClaudeAgentOptionsasync def analyze_codebase(): # 启用 Task 工具让 Claude 自动生成子代理 async for message in query( prompt="分析这个代码库的安全漏洞", options=ClaudeAgentOptions( allowed_tools=["Read", "Glob", "Grep", "Task"] ) ): print(message) # Claude 可能会生成子代理用于: # - SQL 注入分析 # - XSS 漏洞扫描 # - 依赖审计

3. 专业化

不同子代理可以使用不同的模型和工具集，优化成本和性能。

Task 工具的输出

Task 执行完成后，会返回丰富的统计信息：

• result：子代理的执行结果
• usage: Token 使用量统计
• total_cost_usd：本次执行的成本
• duration_ms：执行耗时

这让你能够精确监控每个子代理的资源消耗。

子代理的局限性

需要注意的是，子代理目前不能创建子子代理。即使你在子代理的工具列表中包含了 Task，它也会报告该工具不可用。如果需要多层代理，需要在架构设计时考虑这个限制。

---

四、内置工具深度解析

让我们深入了解每个工具类别的实际使用场景和最佳实践。

文件操作工具：Read、Write、Edit

这三个工具构成了 Agent 与文件系统交互的核心。

Read 工具

Read 是最基础但也最强大的工具之一。它不仅能读取文本文件，还支持：

• 多格式支持：代码文件、配置文件、Markdown、JSON、YAML
• 二进制文件：图片（返回 base64）、PDF（提取文本）
• 行范围读取：Read(path="/src/app.py", start_line=10, end_line=50) 只读取特定行，节省上下文

最佳实践：

# 大文件分段读取,避免上下文溢出options = ClaudeAgentOptions( allowed_tools=["Read"], system_prompt="读取大文件时,先用 Read 获取总行数,然后分段读取")

Write vs Edit

这两个工具的选择经常让人困惑：

场景	推荐工具	原因
创建新文件	Write	直接写入
完全重写文件	Write	更高效
修改几行代码	Edit	精确替换，保留其他内容
批量重构	Edit	可以多次调用，逐步修改

Edit 工具的强大之处：

# Edit 支持精确的字符串替换Edit( path="/src/config.py", old_text='DEBUG = True', new_text='DEBUG = False')# 可以替换多行Edit( path="/src/api.py", old_text='''def old_function(): return "old"''', new_text='''def new_function(): return "new"''')

命令执行工具：Bash、BashOutput、KillBash

Bash 工具是 Claude Agent SDK 中最具争议也最强大的工具之一。

Bash 工具的权限模型

Claude Code 对 Bash 命令有严格的权限控制。默认情况下，只有 117+ 个预定义的安全命令模式 被允许执行。

例如，这些命令默认允许：

• 只读命令：ls, cat, grep, find
• Git 操作：git status, git log, git diff
• 包管理：npm install, pip install

但这些命令默认被阻止：

• 危险操作：rm -rf, sudo, chmod 777
• 网络操作：curl, wget（除非明确允许）
• 系统修改：apt-get, yum

如何自定义 Bash 权限：

// .claude/settings.json{ "allowedTools": ["Bash"], "bashPatterns": [ "npm run test", "docker-compose up -d", "curl https://api.example.com/*" ]}

后台执行模式

Bash 工具支持三种执行模式：

1. 1. 前台执行（默认）: Claude 等待命令完成

2. 2. 后台执行：命令在后台运行，Claude 继续工作

3. 3. 超时控制：通过 BASH_DEFAULT_TIMEOUT_MS 环境变量设置

实际案例：

// 启动开发服务器(后台)await agent.run({ prompt: "启动开发服务器并继续工作", options: { allowedTools: ["Bash", "BashOutput"], bashPatterns: ["npm run dev"] }});// Claude 会:// 1. 执行 Bash("npm run dev", background=true)// 2. 继续处理其他任务// 3. 定期用 BashOutput 检查服务器状态// 4. 如果需要,用 KillBash 终止进程

安全陷阱与防护

社区发现了多个 Bash 工具的安全漏洞，Anthropic 已经修复了大部分。但你仍需注意：

• 命令注入：永远不要将用户输入直接拼接到 Bash 命令中
• 权限提升：避免使用 --dangerously-skip-permissions 标志
• 资源耗尽：设置合理的超时和资源限制

搜索工具：Glob vs Grep

这两个工具经常被混淆，但它们服务于不同的目的。

Glob：文件名匹配

# 查找所有 TypeScript 文件Glob("/*.ts")# 查找测试文件Glob("/*.test.{js,ts,jsx,tsx}")# 排除 node_modulesGlob("src//*.py", exclude=["/node_modules/"])

Grep：内容搜索

Grep 底层使用 ripgrep(rg)，这是一个极快的搜索工具。

# 查找所有包含 "TODO" 的文件Grep(pattern="TODO", path="./src")# 正则表达式搜索Grep(pattern=r"function/s+/w+/(", path="./src")# 区分大小写Grep(pattern="API_KEY", case_sensitive=True)

性能对比：

任务	Glob	Grep	推荐
查找所有 .py 文件	✅ 快	❌ 慢	Glob
查找包含特定函数的文件	❌ 不支持	✅ 快	Grep
查找最近修改的文件	✅ 支持	❌ 不支持	Glob
复杂正则搜索	❌ 不支持	✅ 强大	Grep

MCP 集成：无限扩展的可能

Model Context Protocol (MCP) 是 Claude Agent SDK 最强大的扩展机制。

什么是 MCP?

MCP 是 Anthropic 定义的标准协议，让 AI Agent 能够连接到外部服务和数据源。把它想象成“AI 的 API”。

内置 MCP 支持

SDK 提供了两个工具来使用 MCP:

• ListMcpResources：列出可用的 MCP 服务器和资源
• ReadMcpResource：读取特定资源的内容

创建自定义 MCP 服务器

import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";import { z } from "zod";// 创建数据库查询 MCP 服务器const dbServer = createSdkMcpServer({ name: "database", version: "1.0.0", tools: [ tool({ name: "query_users", description: "查询用户数据库", parameters: z.object({ filter: z.string().describe("SQL WHERE 子句") }), execute: async ({ filter }) => { // 执行数据库查询 const results = await db.query(`SELECT * FROM users WHERE ${filter}`); return { users: results }; } }) ]});// 在 Agent 中使用const agent = new Agent({ mcpServers: { database: dbServer }, allowedTools: ["ListMcpResources", "ReadMcpResource"]});

社区 MCP 服务器生态

已有超过 100+ 个社区贡献的 MCP 服务器，覆盖：

• 开发工具： GitHub, GitLab, Linear, Jira
• 云服务： AWS, Google Cloud, DigitalOcean
• 协作工具： Slack, Microsoft Teams, Miro
• 数据存储： Google Drive, Box, Dropbox
• 监控工具： Sentry, Datadog

MCP vs 自定义工具

特性	MCP 服务器	自定义工具
标准化	✅ 跨平台兼容	❌ SDK 特定
可重用性	✅ 社区共享	❌ 项目内部
开发复杂度	中等	低
性能	略慢（进程间通信）	快（同进程）
适用场景	外部服务集成	简单内部逻辑

---

五、工具组合模式与最佳实践

理解单个工具只是第一步，真正的力量来自于工具的组合使用。

模式 1：读取-分析-修改循环

这是最常见的代码重构模式：

from claude_agent_sdk import query, ClaudeAgentOptionsasync def refactor_codebase(): async for message in query( prompt=""" 重构 src/ 目录下的所有 Python 文件: 1. 用 Glob 找到所有 .py 文件 2. 用 Read 读取每个文件 3. 分析代码质量问题 4. 用 Edit 修复问题 5. 用 Bash 运行测试验证 """, options=ClaudeAgentOptions( allowed_tools=["Glob", "Read", "Edit", "Bash"], bashPatterns=["pytest *"] ) ): print(message)

模式 2：搜索-过滤-聚合

适用于代码审计和分析：

// 查找所有 API 密钥泄露const agent = new Agent({ allowedTools: ["Grep", "Read", "Write"], systemPrompt: ` 安全审计流程: 1. 用 Grep 搜索可疑模式(API_KEY, SECRET, PASSWORD) 2. 用 Read 读取匹配的文件 3. 分析是否为真实泄露 4. 用 Write 生成审计报告 `});await agent.run({ prompt: "审计代码库中的敏感信息泄露"});

模式 3：并行子代理 + 结果聚合

利用 Task 工具实现复杂的多任务处理：

options = ClaudeAgentOptions( allowed_tools=["Task", "Read", "Write"], agents={ "security-scanner": AgentDefinition( description="安全扫描专家", tools=["Grep", "Read"], model="haiku" # 快速扫描用轻量模型 ), "performance-analyzer": AgentDefinition( description="性能分析专家", tools=["Bash", "Read"], model="sonnet" ), "doc-generator": AgentDefinition( description="文档生成专家", tools=["Read", "Write"], model="haiku" ) })# Claude 会自动并行执行三个子代理async for msg in query( prompt="全面分析这个项目:安全、性能、文档", options=options): print(msg)

模式 4: MCP 驱动的外部集成

将内置工具与 MCP 服务器结合：

const agent = new Agent({ allowedTools: ["Read", "Grep", "ListMcpResources", "ReadMcpResource"], mcpServers: { github: { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"], env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN } }, database: { command: "npx", args: ["-y", "@modelcontextprotocol/server-postgres"], env: { DATABASE_URL: process.env.DATABASE_URL } } }});await agent.run({ prompt: ` 分析最近的 GitHub PR: 1. 用 MCP GitHub 获取最近 10 个 PR 2. 用 Read 读取相关代码文件 3. 用 MCP Database 查询相关的 bug 报告 4. 生成代码审查报告 `});

最佳实践总结

1. 工具选择原则

• 最小权限：只授予完成任务所需的最少工具
• 性能优先：优先使用快速工具（Glob > Grep > Read）
• 安全第一： Bash 工具需要严格的权限控制

2. 上下文管理

# ❌ 不好:一次性读取所有文件options = ClaudeAgentOptions( allowed_tools=["Read"], system_prompt="读取 src/ 下所有文件并分析")# ✅ 好:分阶段读取options = ClaudeAgentOptions( allowed_tools=["Glob", "Read"], system_prompt=""" 1. 用 Glob 列出文件 2. 按优先级排序 3. 逐个读取和分析 4. 只读取必要的文件 """)

3. 错误处理

const agent = new Agent({ allowedTools: ["Bash", "Read"], onToolUse: (tool, input) => { console.log(`[TOOL] ${tool}:`, input); }, onError: (error) => { if (error.tool === "Bash") { console.error("Bash 命令失败,尝试回退方案"); // 实现重试逻辑 } }});

4. 成本优化

策略	节省	实现
使用 Glob 代替 Read 遍历	90%	先用 Glob 过滤，再 Read
子代理用 Haiku 模型	80%	简单任务用轻量模型
限制 Read 行数	50%	指定 start_line/end_line
批量操作	30%	一次 Edit 多处修改

---

六、工具权限与安全模型

Claude Agent SDK 的安全模型是其生产就绪的关键。

权限模式

SDK 提供三种权限模式：

1. Interactive（交互模式）

options = ClaudeAgentOptions( permission_mode="interactive" # 默认)# 每次工具调用都需要用户确认

2. AcceptEdits（自动接受编辑）

options = ClaudeAgentOptions( permission_mode="acceptEdits")# 自动允许 Read、Edit、Write# 但 Bash 仍需确认

3. BypassPermissions（绕过权限）

options = ClaudeAgentOptions( permission_mode="bypassPermissions")# ⚠️ 危险:所有工具调用都自动执行# 仅用于可信环境

细粒度工具控制

options = ClaudeAgentOptions( allowed_tools=["Read", "Grep", "Bash"], denied_tools=["Write", "Edit"], # 明确禁止 bash_patterns=[ "git status", "git diff", "npm test" ] # 只允许这些 Bash 命令)

沙箱与隔离

文件系统隔离：

options = ClaudeAgentOptions( allowed_tools=["Read", "Write"], working_directory="/project/sandbox", # 限制工作目录 allowed_paths=[ "/project/sandbox/", "/project/config.json" # 白名单特定文件 ])

网络隔离：

options = ClaudeAgentOptions( allowed_tools=["WebFetch"], allowed_domains=[ "api.github.com", "*.anthropic.com" ], blocked_domains=[ "*.internal.company.com" # 阻止内网访问 ])

审计与监控

import { Agent } from "@anthropic-ai/claude-agent-sdk";const agent = new Agent({ allowedTools: ["Read", "Write", "Bash"], // 工具调用钩子 onToolUse: (tool, input, output) => { // 记录到审计日志 auditLog.write({ timestamp: new Date(), tool, input, output, user: getCurrentUser() }); // 实时告警 if (tool === "Bash" && input.includes("rm")) { alert.send("检测到危险的 Bash 命令"); } }, // 成本跟踪 onTokenUsage: (usage) => { costTracker.record({ input_tokens: usage.input_tokens, output_tokens: usage.output_tokens, cost_usd: usage.total_cost_usd }); }});

---

七、从 claude-code-sdk 迁移到 claude-agent-sdk

如果你之前使用的是旧版 SDK，需要注意以下变化：

1. 包名和导入变化

# 旧版from claude_code_sdk import query, ClaudeCodeOptions# 新版from claude_agent_sdk import query, ClaudeAgentOptions

2. 系统提示的重要变化

这是最关键的破坏性变更：新版 SDK 不再默认使用 Claude Code 的系统提示。

# 旧版:默认使用 Claude Code 系统提示options = ClaudeCodeOptions(allowed_tools=["Read"])# 新版:需要显式指定options = ClaudeAgentOptions( allowed_tools=["Read"], system_prompt={"type": "preset", "preset": "claude_code"} # 显式指定)

3. 新增子代理能力

新版最大的增强就是 Task 工具和子代理系统，这是旧版所没有的。

---

总结

Claude Agent SDK 的工具体系代表了 AI Agent 开发的最新范式：

1. 1. 18+ 内置工具 覆盖文件操作、命令执行、搜索、Web、用户交互、任务管理、代理编排、计划模式、技能调用和工具发现等核心场景

2. 2. 三层任务概念 明确区分 Task 工具（子代理编排）、TodoWrite 工具（任务列表管理）和 Tasks 系统（Claude Code 产品层的持久化任务管理）

3. 3. WebSearch 服务端工具 通过 Anthropic 服务端执行搜索，让 Claude 获得实时信息能力

4. 4. Task 工具 引入子代理编排能力，实现复杂任务的专业化处理和并行执行，支持前台和后台两种执行模式

5. 5. TodoWrite 工具 让 AI 的工作计划可见，实现透明的任务管理和进度追踪

6. 6. Plan Mode 通过 EnterPlanMode 和 ExitPlanMode 工具，实现“思考”与“执行”的分离，确保复杂变更的安全性

7. 7. Skill 工具 作为元工具，支持动态加载和执行预定义的工作流，实现知识封装和团队协作

8. 8. ToolSearch 工具 解决大型工具集的上下文污染问题，支持按需动态加载工具，节省 60-80% 的上下文 token

9. 9. 工具组合模式 通过合理组合内置工具，实现复杂的自动化工作流

10. 10. MCP 生态系统 100+ 社区 MCP 服务器，无限扩展 Agent 能力

11. 11. 安全模型 细粒度的权限控制和审计机制，确保生产环境安全

12. 12. 活跃生态 从 Skills 到 Plugins，持续丰富的社区扩展

如果你正在构建 AI Agent 应用，Claude Agent SDK 的这套工具体系值得深入学习和实践。特别是 Task 工具的子代理编排能力和 TodoWrite 工具的任务管理能力，它们让 Claude 从“更好的聊天界面”真正转变为“自主开发代理”。

---

## 最后

近期科技圈传来重磅消息：行业巨头英特尔宣布大规模裁员2万人，传统技术岗位持续萎缩的同时，另一番景象却在AI领域上演——AI相关技术岗正开启“疯狂扩招”模式！据行业招聘数据显示，具备3-5年大模型相关经验的开发者，在大厂就能拿到50K×20薪的高薪待遇，薪资差距肉眼可见！

业内资深HR预判：不出1年，“具备AI项目实战经验”将正式成为技术岗投递的硬性门槛。在行业迭代加速的当下，“温水煮青蛙”式的等待只会让自己逐渐被淘汰，与其被动应对，不如主动出击，抢先掌握AI大模型核心原理+落地应用技术+项目实操经验，借行业风口实现职业翻盘！

深知技术人入门大模型时容易走弯路，我特意整理了一套全网最全最细的大模型零基础学习礼包，涵盖入门思维导图、经典书籍手册、从入门到进阶的实战视频、可直接运行的项目源码等核心内容。这份资料无需付费，免费分享给所有想入局AI大模型的朋友！

👇👇扫码免费领取全部内容👇👇

部分资料展示

1、 AI大模型学习路线图

2、 全套AI大模型应用开发视频教程

从入门到进阶这里都有，跟着老师学习事半功倍。

3、 大模型学习书籍&文档

4、 AI大模型最新行业报告

2025最新行业报告，针对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。

5、大模型大厂面试真题

整理了百度、阿里、字节等企业近三年的AI大模型岗位面试题，涵盖基础理论、技术实操、项目经验等维度，每道题都配有详细解析和答题思路，帮你针对性提升面试竞争力。

6、大模型项目实战&配套源码

学以致用，在项目实战中检验和巩固你所学到的知识，同时为你找工作就业和职业发展打下坚实的基础。

👉学会后的收获：👈

• 基于大模型全栈工程实现（前端、后端、产品经理、设计、数据分析等），通过这门课可获得不同能力；

• 能够利用大模型解决相关实际项目需求： 大数据时代，越来越多的企业和机构需要处理海量数据，利用大模型技术可以更好地处理这些数据，提高数据分析和决策的准确性。因此，掌握大模型应用开发技能，可以让程序员更好地应对实际项目需求；

• 基于大模型和企业数据AI应用开发，实现大模型理论、掌握GPU算力、硬件、LangChain开发框架和项目实战技能， 学会Fine-tuning垂直训练大模型（数据准备、数据蒸馏、大模型部署）一站式掌握；

• 能够完成时下热门大模型垂直领域模型训练能力，提高程序员的编码能力： 大模型应用开发需要掌握机器学习算法、深度学习框架等技术，这些技术的掌握可以提高程序员的编码能力和分析能力，让程序员更加熟练地编写高质量的代码。

• 👇👇扫码免费领取全部内容👇👇

这些资料真的有用吗？

这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理，现任上海殷泊信息科技CEO，其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证，服务航天科工、国家电网等1000+企业，以第一作者在IEEE Transactions发表论文50+篇，获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。

资料内容涵盖了从入门到进阶的各类视频教程和实战项目，无论你是小白还是有些技术基础的技术人员，这份资料都绝对能帮助你提升薪资待遇，转行大模型岗位。

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】