Claude Code SDK 中的子代理是由主代理编排的专门化 AI。 使用子代理进行上下文管理和并行化。

本指南解释了 SDK 应用程序如何与通过 markdown 文件创建的子代理进行交互和利用。

​
概述

子代理专门通过基于文件系统的方法创建，即在指定目录中放置带有 YAML 前置元数据的 markdown 文件。然后 SDK 可以在执行期间调用这些预定义的子代理。

​
使用子代理的好处

​
上下文管理

子代理与主代理保持独立的上下文，防止信息过载并保持交互的专注性。这种隔离确保专门化任务不会用无关细节污染主对话上下文。

示例：research-assistant 子代理可以探索数十个文件和文档页面，而不会用所有中间搜索结果使主对话变得混乱 - 只返回相关发现。

​
并行化

多个子代理可以并发运行，显著加速复杂工作流程。

示例：在代码审查期间，您可以同时运行 style-checker、security-scanner 和 test-coverage 子代理，将审查时间从几分钟缩短到几秒钟。

​
专门化指令和知识

每个子代理都可以有定制的系统提示，具有特定的专业知识、最佳实践和约束。

示例：database-migration 子代理可以拥有关于 SQL 最佳实践、回滚策略和数据完整性检查的详细知识，这些在主代理的指令中是不必要的噪音。

​
工具限制

子代理可以被限制为特定工具，减少意外操作的风险。

示例：doc-reviewer 子代理可能只能访问 Read 和 Grep 工具，确保它可以分析但永远不会意外修改您的文档文件。

​
创建子代理

子代理被定义为特定目录中的 markdown 文件：

  • 项目级别：.claude/agents/*.md - 仅在当前项目中可用
  • 用户级别：~/.claude/agents/*.md - 在所有项目中可用

​
文件格式

每个子代理都是一个带有 YAML 前置元数据的 markdown 文件：

---
name: code-reviewer
description: Expert code review specialist. Use for quality, security, and maintainability reviews.
tools: Read, Grep, Glob, Bash  # Optional - inherits all tools if omitted
---

Your subagent's system prompt goes here. This defines the subagent's
role, capabilities, and approach to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

​
配置字段

字段必需描述
name是使用小写字母和连字符的唯一标识符
description是何时使用此子代理的自然语言描述
tools否允许的工具的逗号分隔列表。如果省略，则继承所有工具

​
SDK 如何使用子代理

使用 Claude Code SDK 时，文件系统中定义的子代理会自动可用。Claude Code 将：

  1. 自动检测子代理 从 .claude/agents/ 目录
  2. 基于任务匹配自动调用它们
  3. 使用它们的专门化提示 和工具限制
  4. 为每个子代理调用维护独立上下文

SDK 遵循文件系统配置 - 没有在运行时以编程方式创建子代理的方法。所有子代理必须在 SDK 执行之前定义为文件。

​
示例子代理

有关子代理的全面示例，包括代码审查员、测试运行器、调试器和安全审计员，请参阅主要子代理指南。该指南包括创建有效子代理的详细配置和最佳实践。

​
SDK 集成模式

​
自动调用

SDK 将根据任务上下文自动调用适当的子代理。确保您的子代理的 description 字段清楚地指示何时应该使用它：

---
name: performance-optimizer
description: Use PROACTIVELY when code changes might impact performance. MUST BE USED for optimization tasks.
tools: Read, Edit, Bash, Grep
---

​
显式调用

用户可以在他们的提示中请求特定的子代理：

// When using the SDK, users can explicitly request subagents:
const result = await query({
  prompt: "Use the code-reviewer subagent to check the authentication module"
});

​
工具限制

子代理可以通过 tools 字段限制工具访问：

  • 省略该字段 - 子代理继承所有可用工具（默认）
  • 指定工具 - 子代理只能使用列出的工具

只读分析子代理的示例：

---
name: code-analyzer
description: Static code analysis and architecture review
tools: Read, Grep, Glob  # No write or execute permissions
---

You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.

​
相关文档