Subagents 入门

什么是 Subagent

Subagent（子代理）是你可以委派任务的「助手代理」。主代理把一项相对独立的工作交给子代理去完成，子代理在自己的上下文里干活，干完把结果交回来。

为什么要用子代理

• 保持主上下文干净：子代理的中间过程不会塞满主对话
• 专业分工：可以为不同任务配置不同的子代理
• 并行与委派：把大任务拆成可独立完成的小块

创建与使用子代理

你可以为特定职责定义一个子代理：给它名字、说明它负责什么、它能用哪些工具。之后主代理在合适的时候就会把任务派给它。

一个子代理包含什么

• 名称与职责：它是谁、负责什么
• 说明（instructions）：它该如何工作
• 工具范围：它被允许使用哪些工具

何时该委派

当一项工作相对独立、会产生大量中间过程、或者需要专门的处理方式时，就适合交给子代理。简单的小事直接做就好，不必都委派。

多子代理协作

单个 Subagent 已经很强大，但真正的效率提升来自多个 Subagent 的协作。本课介绍两种核心协作模式：扇出（fan-out）和流水线（pipeline）。

扇出模式：并行处理多个任务

扇出模式由一个编排者（orchestrator）启动多个并行 Subagent，每个 Subagent 处理独立的子任务，最后编排者收集所有结果进行汇总。这是最常见的并行加速模式。

• 编排者负责拆分任务、分配工作、汇总结果
• 每个 Subagent 拥有独立的 context window
• Subagent 之间通过文件系统共享数据，而不是直接通信

# 编排者 Prompt 示例

请并行启动 3 个 Subagent 分析以下三个模块，每个 Subagent 将分析结果写入指定文件：

Subagent 1：分析 src/auth/ 目录，将结果写入 /tmp/analysis-auth.md
Subagent 2：分析 src/api/ 目录，将结果写入 /tmp/analysis-api.md
Subagent 3：分析 src/db/ 目录，将结果写入 /tmp/analysis-db.md

每个分析应包含：代码质量评分（1-10）、主要问题列表、改进建议。

所有 Subagent 完成后，读取三个文件并生成综合报告 /tmp/analysis-summary.md。

流水线模式：串行传递数据

流水线模式中，Subagent A 的输出文件成为 Subagent B 的输入。适合需要依次处理、前一步结果决定后一步行为的场景。例如：Subagent A 提取数据 → Subagent B 分析数据 → Subagent C 生成报告。

工具与权限范围

默认情况下 Subagent 拥有与主 Agent 相同的工具权限。但在自动化工作流中，你通常希望限制 Subagent 的权限，只给它完成任务所需的最小工具集。

为什么要限制 Subagent 的权限

在自动化工作流中，Subagent 可能会在无人监督的情况下执行操作。给予过多权限会带来风险：Subagent 可能误删文件、发起网络请求，或修改不该修改的内容。最小权限原则能有效降低意外损失。

• 只读 Subagent：只能读取文件，不能写入或执行命令
• 受限写入：只能写入指定目录下的文件
• 无网络：禁止 Subagent 发起外部网络请求

在 Prompt 中指定允许的工具

在启动 Subagent 时，通过 Prompt 明确说明它可以使用哪些工具，以及哪些操作是被禁止的。虽然这不是硬性的技术限制，但清晰的指令能有效引导 Subagent 的行为边界。

# 受限 Subagent Prompt 示例

你是一个只读分析 Agent。你只能：
- 读取文件（Read 工具）
- 列出目录内容（Bash ls 命令）

你不能：
- 写入或修改任何文件
- 运行除 ls 之外的 shell 命令
- 发起网络请求

请分析 src/ 目录的结构，将你的发现以文字形式返回（不要写入任何文件）。

何时该委派

不是所有任务都适合委派给 Subagent。学会识别好的委派场景和糟糕的委派场景，是高效使用 Subagent 的关键。

适合委派的任务特征

最适合委派的任务具备三个特征：任务之间依赖少（可以并行）、输出相互独立（不会互相干扰）、没有共享的可变状态（不会同时修改同一个文件）。

• 好的委派：并行分析 5 个独立的日志文件
• 好的委派：同时为 3 个不同模块生成测试用例
• 好的委派：并发翻译 10 篇独立文章

糟糕的委派场景

当两个 Subagent 需要修改同一个文件时，就会产生冲突。这是最常见的委派错误。此外，强依赖前一步结果的任务（非流水线场景）也不适合并行委派。

• 坏的委派：两个 Subagent 都写入同一个 output.md
• 坏的委派：Subagent B 必须等 Subagent A 分析完才能开始
• 坏的委派：任务需要跨 Subagent 维护一个计数器

分解任务的实用方法

将大任务分解时，先画出任务之间的依赖图。没有依赖箭头连接的任务可以并行；有单向依赖的任务适合流水线；有双向依赖的任务不应委派给不同 Subagent。

常见误区

Subagent 出错往往有规律可循。了解最常见的失败模式，能帮你提前设计防护措施。

误区一：Subagent 幻觉文件路径

Subagent 可能会"发明"一个并不存在的文件路径，然后自信地说它已经读取并分析了该文件。解决方法：在 Prompt 中明确提供完整的绝对路径，并要求 Subagent 在读取文件前先验证文件存在。

误区二：多个 Subagent 冲突写文件

当两个 Subagent 同时写入同一个文件时，后写入的内容会覆盖前一个，导致数据丢失。解决方法：为每个 Subagent 分配唯一的输出文件名，例如 output-agent-1.md、output-agent-2.md，由编排者负责合并。

误区三：编排者误解 Subagent 的输出

编排者读取 Subagent 输出时，可能因格式不统一而解析错误。解决方法：在每个 Subagent 的 Prompt 中明确规定输出格式（如 JSON 或固定 Markdown 结构），并要求 Subagent 严格遵守。

• 每个 Subagent 用唯一输出文件，避免冲突
• 明确规定输出格式，方便编排者解析
• 在编排者中记录每个 Subagent 的原始输出，便于调试
• 对关键操作增加验证步骤，而不是假设 Subagent 成功