什么是子代理?
子代理是 Claude Code 可以委派任务的预配置 AI 个性。每个子代理:- 具有特定的目的和专业领域
- 使用与主对话分离的自己的上下文窗口
- 可以配置允许使用的特定工具
- 包含指导其行为的自定义系统提示
主要优势
上下文保护
每个子代理在自己的上下文中操作,防止主对话的污染并保持其专注于高级目标。
专业知识
子代理可以针对特定领域进行详细指令的微调,从而在指定任务上获得更高的成功率。
可重用性
一旦创建,子代理可以在不同项目中使用,并与您的团队共享以实现一致的工作流程。
灵活权限
每个子代理可以有不同的工具访问级别,允许您将强大的工具限制为特定的子代理类型。
快速开始
创建您的第一个子代理:1
打开子代理界面
运行以下命令:
2
选择'创建新代理'
选择是创建项目级还是用户级子代理
3
定义子代理
- 推荐:首先使用 Claude 生成,然后自定义使其成为您的
- 详细描述您的子代理以及何时应该使用它
- 选择您想要授予访问权限的工具(或留空以继承所有工具)
- 界面显示所有可用工具,使选择变得容易
- 如果您正在使用 Claude 生成,您也可以通过按
e在您自己的编辑器中编辑系统提示
4
保存并使用
您的子代理现在可用!Claude 将在适当时自动使用它,或者您可以显式调用它:
子代理配置
文件位置
子代理存储为带有 YAML 前言的 Markdown 文件,位于两个可能的位置:| 类型 | 位置 | 范围 | 优先级 |
|---|---|---|---|
| 项目子代理 | .claude/agents/ | 在当前项目中可用 | 最高 |
| 用户子代理 | ~/.claude/agents/ | 在所有项目中可用 | 较低 |
插件代理
插件可以提供与 Claude Code 无缝集成的自定义子代理。插件代理的工作方式与用户定义的代理完全相同,并出现在/agents 界面中。
插件代理位置:插件在其 agents/ 目录中包含代理(或插件清单中指定的自定义路径)。
使用插件代理:
- 插件代理与您的自定义代理一起出现在
/agents中 - 可以显式调用:“使用来自 security-plugin 的 code-reviewer 代理”
- 可以在适当时由 Claude 自动调用
- 可以通过
/agents界面进行管理(查看、检查)
基于 CLI 的配置
您还可以使用--agents CLI 标志动态定义子代理,该标志接受 JSON 对象:
- 快速测试子代理配置
- 不需要保存的会话特定子代理
- 需要自定义子代理的自动化脚本
- 在文档或脚本中共享子代理定义
文件格式
每个子代理在 Markdown 文件中定义,具有以下结构:配置字段
| 字段 | 必需 | 描述 |
|---|---|---|
name | 是 | 使用小写字母和连字符的唯一标识符 |
description | 是 | 子代理目的的自然语言描述 |
tools | 否 | 特定工具的逗号分隔列表。如果省略,从主线程继承所有工具 |
model | 否 | 此子代理使用的模型。可以是模型别名(sonnet、opus、haiku)或 'inherit' 以使用主对话的模型。如果省略,默认为配置的子代理模型 |
模型选择
model 字段允许您控制子代理使用哪个 AI 模型:
- 模型别名:使用可用别名之一:
sonnet、opus或haiku 'inherit':使用与主对话相同的模型(对一致性有用)- 省略:如果未指定,使用为子代理配置的默认模型(
sonnet)
使用
'inherit' 在您希望子代理适应主对话的模型选择时特别有用,确保整个会话中的一致能力和响应风格。可用工具
子代理可以被授予访问 Claude Code 的任何内部工具。有关可用工具的完整列表,请参阅工具文档。推荐: 使用
/agents 命令修改工具访问权限 - 它提供了一个交互式界面,列出所有可用工具,包括任何连接的 MCP 服务器工具,使选择您需要的工具变得更容易。- 省略
tools字段以从主线程继承所有工具(默认),包括 MCP 工具 - 指定单个工具作为逗号分隔列表以进行更精细的控制(可以手动编辑或通过
/agents编辑)
tools 字段时,子代理继承主线程可用的所有 MCP 工具。
管理子代理
使用 /agents 命令(推荐)
/agents 命令为子代理管理提供了一个全面的界面:
- 查看所有可用的子代理(内置、用户和项目)
- 通过引导设置创建新的子代理
- 编辑现有的自定义子代理,包括其工具访问权限
- 删除自定义子代理
- 查看当存在重复时哪些子代理处于活动状态
- 轻松管理工具权限,提供可用工具的完整列表
直接文件管理
您也可以通过直接处理子代理文件来管理它们:有效使用子代理
自动委派
Claude Code 基于以下内容主动委派任务:- 您请求中的任务描述
- 子代理配置中的
description字段 - 当前上下文和可用工具
为了鼓励更多主动的子代理使用,在您的
description 字段中包含诸如”主动使用”或”必须使用”之类的短语。显式调用
通过在命令中提及特定子代理来请求它:示例子代理
代码审查员
调试器
数据科学家
最佳实践
- 从 Claude 生成的代理开始:我们强烈建议使用 Claude 生成您的初始子代理,然后对其进行迭代以使其个人化。这种方法为您提供最佳结果 - 一个您可以根据特定需求自定义的坚实基础。
- 设计专注的子代理:创建具有单一、明确职责的子代理,而不是试图让一个子代理做所有事情。这提高了性能并使子代理更可预测。
- 编写详细的提示:在您的系统提示中包含具体的指令、示例和约束。您提供的指导越多,子代理的表现就越好。
- 限制工具访问:只授予子代理目的所必需的工具。这提高了安全性并帮助子代理专注于相关操作。
- 版本控制:将项目子代理检入版本控制,这样您的团队就可以从中受益并协作改进它们。
高级用法
链接子代理
对于复杂的工作流程,您可以链接多个子代理:动态子代理选择
Claude Code 基于上下文智能选择子代理。使您的description 字段具体且面向行动,以获得最佳结果。
性能考虑
- 上下文效率:代理有助于保护主上下文,实现更长的整体会话
- 延迟:子代理每次被调用时都从干净的状态开始,可能会增加延迟,因为它们需要收集有效完成工作所需的上下文。