一文读懂什么是 Subagent

在单个大模型助手能完成越来越多任务之后，新的问题也出现了：
一个 Agent 如果同时负责搜索、规划、编码、测试、审查、总结，很容易上下文过载、职责混乱、工具权限过大。

上下文过载

大模型的上下文对话都是线性追加的，不会自动过期。如果大模型分析500行日志，判断推理报错原因，然后再执行其他任务时，其他任务处理过程中大模型会带着500行日志的”噪声“，表现出混乱等
职责混乱

一个对话过程中既写代码又做测试很难发现问题
工具权限过大

对于一些不同的任务赋予不同权限，比如代码开发只按规定的设计文档写代码，不修改设计文档；代码检视只看代码不修改，。

SubAgent（子代理）就是为了解决这个问题而出现的工程化模式。它的核心思想很简单：把复杂任务拆给多个专门 Agent，每个 Agent 只负责自己擅长的部分，最后由主 Agent 汇总或继续执行。

什么是Subagent ？

Subagent 是由主 Agent 调度的专用 Agent。它通常拥有独立上下文、独立系统提示词、独立工具权限，并负责完成某个明确子任务。

在 Claude Code 官方文档中，subagent 被描述为“specialized AI assistants that operate with their own isolated context windows”。也就是说，每个 subagent 都有自己的上下文窗口和任务边界，完成任务后只把结果摘要返回给主 Agent。

OpenAI 官方 Agents 文档则把类似模式抽象为多 agent 编排（multi-agent orchestration），常见方式包括：

Handoffs：把对话控制权交给另一个专业 Agent
Agents as Tools：主 Agent 保持控制权，把其他 Agent 当工具调用

两者表达不同，但工程目标一致：让复杂任务由多个职责清晰的 Agent 协作完成。

为什么需要 Subagent？

单 Agent 架构的优势是简单，但复杂任务中会出现四个明显问题。

1) 上下文污染

主 Agent 既要读代码，又要跑测试，还要写总结。大量中间信息会挤占上下文，影响后续判断。

Subagent 可以把中间探索隔离起来。主 Agent 只接收“必要结论”，不需要承载所有探索过程。

任务特点：执行过程中产生大量中间信息，但结论往往只有一个

2) 职责不清

一个 Agent 同时做研究、实现、测试、审查，很容易在角色之间切换失焦。 Subagent 允许每个子代理只负责一个领域。

例如：

explore-agent：只读代码、找上下文
implementation-agent：只做实现
review-agent：只审查风险
test-agent：只运行和分析测试

任务特点：可以拆成清晰阶段的流水线式任务

3) 工具权限过大

不是所有任务都需要写文件、运行命令或访问外部服务。
Subagent 可以限制工具权限，让只读任务保持只读，降低误操作风险。
任务特点：专人专权

4) 并行能力不足

多个独立子任务如果都由一个 Agent 串行处理，会浪费时间。 Subagent 可以并行探索不同模块，再把结果汇总给主 Agent。

任务特点：并行

Subagent本质上就是三件事：隔离、约束、复用

如何使用Subagents

Subagent不像skill一样形成了统一的规范标准，当前不同的Agent支持的能力也有不同。

几乎所有的Agent支持以下方式调用：

由主代理根据其描述自动调用以执行专门任务。
通过在消息中手动显式调用子代理。例如：

claude code/cursor:
```
/review help me review code
```
opencode：
```
@review help me review code
```

Claude Code 中的 Subagent

Claude Code 的 subagent 更偏“任务委派 + 上下文隔离”。

官方文档强调几个特点：

每个 subagent 有独立上下文窗口
每个 subagent 可以有自定义系统提示词
每个 subagent 可以配置独立工具访问权限
Claude 会根据 subagent 的 description 判断何时委派
subagent 完成后把结果返回给主 Agent

Claude Code 还提供内置 subagent，例如：

Explore：快速只读探索代码库
Plan：在规划阶段收集上下文
General-purpose：处理复杂、多步骤任务

Claude Code 自定义 Subagent 示例

一个文件系统风格的 Claude Code subagent 通常可以放在 .claude/agents/ 下：

---
name: code-reviewer
description: Reviews code changes for correctness, maintainability, security risks, and missing tests. Use after implementation or before creating a pull request.
tools: Read, Grep, Bash
---

# Code Reviewer

You are a focused code review subagent.

## Responsibilities

1. Inspect changed files and related tests.
2. Identify correctness bugs, security risks, and regression risks.
3. Prioritize findings by severity.
4. Return concise review findings with file references.

## Constraints

- Do not modify files.
- Do not run destructive commands.
- Focus on actionable issues, not style preferences.

这个 subagent 的关键不是“写得长”，而是边界清楚：

什么时候触发：实现后、PR 前
做什么：审查风险
不做什么：不修改文件
可用工具：只读为主

Claude Code中Subagent配置字段

字段	类型	必填	描述
`name`	string	是	唯一的标识符。使用小写字母和连字符。
`description`	string	是	显示在 Task 工具提示中的简短描述。智能体会据此决定是否委派任务。
`tools`	string	否	工具白名单（如Read、Grep、Glob等），省略则继承主对话的全部内容。如果要使用Skill，不要放在这里而是放在`skill`字段中
`disallowedTools`	string	否	工具黑白名单
`model`	string	否	要使用的模型
`permissionMode`	string	否	权限模式，支持`default, `auto`,`acceptEdits`, `bypassPermissions`等
`maxTurns`	string	否	subagent停止前的最大轮数
`skills`	string	否	不会自动继承“主对话已经使用过的 skill 上下文”。启动时加载到subagent上下文中，注入完整的技能内容，并不仅仅是`description`字段。
`mcpServers`	string	否	支持的mcp服务器名称
`hooks`	string	否	子代理专属的生命周期hook
`memory`	string	否	持久化记忆范围，可选`user`、`project`、`local`等

OpenCode中的Subagent

参考OpenCode代理

OpenCode 中有两种类型的代理：主代理和子代理。OpenCode 内置了两个主代理：Build 和 Plan，三个子代理General、Explore 和 Scout。

OpenCode支持将子代理放在：

全局：~/.config/opencode/agents/
项目级：.opencode/agents/

OpenCode自定义 Subagent 示例

放在~/.config/opencode/agents/review.md

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

Markdown 文件名即为代理名称。例如，review.md 会创建一个名为 review 的代理。

Cursor中的Subagent

参考Cursor子代理

Cursor支持将子代理放在：

类型	位置	适用范围
项目子智能体	`.cursor/agents/`	仅限当前项目
	`.claude/agents/`	仅限当前项目 (兼容 Claude)
	`.codex/agents/`	仅限当前项目 (兼容 Codex)
用户子智能体	`~/.cursor/agents/`	当前用户的所有项目
	`~/.claude/agents/`	当前用户的所有项目 (兼容 Claude)
	`~/.codex/agents/`	当前用户的所有项目 (兼容 Codex)

名称冲突时，项目子智能体优先。如果多个位置包含同名子智能体，.cursor/ 的优先级高于 .claude/ 和 .codex/。

Cursor中使用Subagent示例

每个子智能体都是一个包含 YAML frontmatter 的 markdown 文件：

---
name: security-auditor
description: Security specialist. Use when implementing auth, payments, or handling sensitive data.
model: inherit
readonly: true
---

You are a security expert auditing code for vulnerabilities.

When invoked:
1. Identify security-sensitive code paths
2. Check for common vulnerabilities (injection, XSS, auth bypass)
3. Verify secrets are not hardcoded
4. Review input validation and sanitization

Report findings by severity:
- Critical (must fix before deploy)
- High (fix soon)
- Medium (address when possible)

Cursor中Subagent配置字段

字段	类型	必填	默认值	描述
`name`	string	否	根据文件名生成	显示名称和标识符。使用小写字母和连字符。
`description`	string	否	—	显示在 Task 工具提示中的简短描述。智能体会据此决定是否委派任务。
`model`	string	否	`inherit`	要使用的模型：`inherit` 或指定的模型 ID。参阅模型配置。
`readonly`	boolean	否	`false`	如果为 `true`，子智能体将以受限的写入权限运行 (不能编辑文件，也不能执行会更改状态的 shell 命令) 。
`is_background`	boolean	否	`false`	如果为 `true`，子智能体将在后台运行，不会阻塞父智能体。

使用子代理Subagents注意点

Subagent不会自动继承“主对话已经使用过的 skill 上下文”。

子代理是一个独立执行上下文，不会自动看到主对话里的用户消息、历史推理、已读文件、已调用 skill 或前面做过的步骤。
主代理需要在创建 subagent 时，把任务背景、目标、约束、相关文件、需要遵守的规则写进 subagent prompt。
如果希望子代理使用某个 skill，最好在 subagent prompt 里明确要求它读取/遵守该 skill，必要时给出 skill 路径或名称。

子代理嵌套调用深度为1

即Subagent不能再调用Subagent，原因主要是：

子代理是隔离上下文：它不会天然继承主对话完整背景，也不一定拥有和主代理完全相同的工具权限。
递归调度容易失控：可能产生无限嵌套、成本暴涨、任务重复、结果难追踪。
责任边界会变模糊：主代理很难知道孙代理做了什么、是否遵守约束、是否和其他代理冲突。
集成风险更高：多个层级的代理如果都在探索或改代码，容易出现重复修改、互相覆盖、范围膨胀。
当前推荐模式是“主代理编排，子代理执行”：子代理完成一个清晰、自包含的任务，然后把发现、建议或结果返回给主代理。

多Subagents设计模式

模式一集中式编排

以调研报告任务为例，这种模式下主代理Supervisor负责编排任务，并把各自子任务委派给SubAgent-A,SubAgent-B,SubAgent-C分别负责不同维度的调研

graph TD
A["Supervisor(主代理)"]
B1["SubAgent-A(搜索维度1)"]
B2["SubAgent-B(搜索维度2)"]
B3["SubAgent-C(搜索维度3)"]
A-->B1
A-->B2
A-->B3

这种模式的优点：

SubAgent之间上下文互相隔离，避免信息污染
SubAgent无状态，支持支持任务并行

模式二状态驱动的Agent切换Handoff

Handoff 适合“专业 Agent 应该接管下一轮回复”的场景。比如客服系统中，用户从普通咨询转到退款问题，就可以从 triageAgent handoff 到 refundAgent。

graph LR
A[billingAgent支付]
B[triageAgent判断]
C[refundAgent退款]
A--handoff-->B
B--handoff-->C

Handoff时上下文不是完整传递，而是选择性传递（传递关键信息和结论）。Handoff 的特点是：

控制权转移。后续由被移交的专业 Agent 负责继续对话。
提高模型注意力。保持必要信息连续性同时避免冗余信息污染。

当前agent没有显式支持handoff的机制，需要依赖Prompt+状态约束+工程结构实现

Claude Code 示例

Claude Code 可以用不同 agent 作为主会话角色，例如：

planner agent
  -> 输出 HANDOFF_TO_IMPLEMENTER
  -> 外部脚本或用户切换到 implementer agent
  -> implementer 继续主流程

planner 的行为约束可以写成：

你是 planner agent。
你的职责：
1. 澄清需求
2. 拆解任务
3. 判断何时交给 implementer
当需求足够明确时，不要继续实现。
请输出：
HANDOFF_TO: implementer
REASON: ...
CONTEXT: ...
NEXT_GOAL: ...
ACCEPTANCE: ...

implementer 的行为约束：

你是 implementer agent。
当收到 HANDOFF_TO: implementer 的上下文时：
1. 接管任务所有权
2. 不再询问 planner
3. 直接进入实现与验证
4. 如遇到无法决策的问题，再交给 user 或 reviewer
如果要自动化，就用 Claude Code SDK 或脚本做一个 router：检测 `HANDOFF_TO`，然后启动对应 agent 作为新的主执行者。

OpenCode 示例

OpenCode 更适合把多个 agent 都配置成 mode: "all"，这样它们既能作为主 Agent，也能被调用。

概念配置：

{
   
  "agent": {
   
    "planner": {
   
      "mode": "all",
      "prompt": "负责需求澄清和方案拆解。完成后输出 HANDOFF_TO: implementer。"
    },
    "implementer": {
   
      "mode": "all",
      "prompt": "负责接管 planner 的 handoff，上下文充分时直接实现。"
    },
    "reviewer": {
   
      "mode": "all",
      "prompt": "负责接管 implementer 的 handoff，进行审查。"
    }
  }
}

流程示例：

用户 -> planner
planner 输出：
HANDOFF_TO: implementer
REASON: 方案已确认
CONTEXT: ...
NEXT_GOAL: 实现功能
然后切换到 implementer 作为主 agent：
implementer 接收 CONTEXT，继续执行主流程。

如果不用外部 orchestrator，这一步通常是手动切换 agent 并传入 handoff packet。要全自动，就需要脚本监听输出并切换主 agent。

Cursor 示例

Cursor 的 Subagent 更偏“委托”，不是天然的完整 Handoff。所以真正 Handoff 通常这样做：

当前 Agent 输出 handoff packet
用户或自动化流程开启新的 Agent 上下文
新 Agent 使用 packet 继续主流程

示例：

HANDOFF_TO: reviewer

你现在接管任务所有权。之前的 implementer 已完成实现，但没有做最终审查。

已完成：
- 新增串口读超时逻辑
- 新增关闭语义测试
- 运行 translayer 单测通过

请继续：
1. 审查实现是否满足 AGENTS.md
2. 检查测试是否覆盖边界
3. 判断是否可以交付

在 Cursor 中，如果你用 Subagent，严格来说仍是“父 Agent 调用 reviewer”。如果你想要真正 Handoff，就应该把这个 packet 作为新主对话/新 agent 的起始上下文，而不是让 reviewer 完成后回到原 Agent。

模式三路由器模式 Router

对输入进行语义拆分和分发，交由各个Subagent处理后再统一对结果进行整合。路由器模式（Router）的本质是：一个"分发者"根据输入的语义特征，把任务路由给最合适的专家 Subagent 处理，再统一整合结果。

graph TD
A["Router(分发+路由)"]
B["SubAent-A(策略1)"]
C["SubAent-B(策略2)"]
D["SubAent-C(策略3)"]
E["SubAent-C(整合)"]
A-->B-->E
A-->C-->E
A-->D-->E

三种模式对比

模式	核心动作	控制权
集中式编排 (Supervisor)	拆解 + 委派 + 汇总	主 Agent 全程持有
Handoff	移交 + 接管	控制权转移给被移交 Agent
Router	分类 + 分发 + 整合	主 Agent 持有，专家 Agent 只产出

Subagent 的多 Agent 协同案例

下面看几个典型案例。

案例一：代码变更流水线

目标：用户要求“给系统增加一个导出功能，并确保测试通过”。

可以设计 4 个 subagent：

explore-agent：只读代码，找相关模块、入口、测试位置
plan-agent：根据探索结果制定实现方案
test-agent：运行测试并分析失败原因
review-agent：审查变更风险和遗漏测试

流程如下：

flowchart TD
    U[用户需求] --> M[主 Agent]
    M --> E[Explore Subagent]
    E --> M
    M --> P[Plan Subagent]
    P --> M
    M --> I[主 Agent 实现代码]
    I --> T[Test Subagent]
    T --> M
    M --> R[Review Subagent]
    R --> M
    M --> O[最终交付说明]

这个模式的好处是：

探索阶段不污染主上下文
测试分析可独立进行
审查 Agent 能以“新视角”发现问题

案例二：企业客服分流

目标：用户进入客服系统，系统自动判断应该由哪个 Agent 处理。

可以设计：

triage-agent：识别意图
billing-agent：处理账单
refund-agent：处理退款
technical-agent：处理技术问题
human-handoff-agent：转人工

OpenAI 的 handoff 模式适合这个场景：

flowchart TD
    U[用户问题] --> T[Triage Agent]
    T -->|账单| B[Billing Agent]
    T -->|退款| R[Refund Agent]
    T -->|技术问题| Tech[Technical Agent]
    T -->|高风险/无法处理| H[Human Handoff]

这里的重点是：一旦识别为退款问题，退款 Agent 可以接管对话，而不是只返回一个工具结果。

案例三：内容生产工作流

目标：生成一篇技术博客。

可以拆成：

research-agent：查资料、整理事实
outline-agent：生成大纲
writer-agent：写初稿
seo-agent：优化标题、摘要、结构
fact-check-agent：核查引用和统计数据

流程可以是并行和串行结合：

flowchart TD
    Topic[文章主题] --> Research[Research Agent]
    Topic --> SEO[SEO Agent]
    Research --> Outline[Outline Agent]
    SEO --> Outline
    Outline --> Writer[Writer Agent]
    Writer --> FactCheck[Fact-check Agent]
    FactCheck --> Final[最终文章]

这个案例适合 “Agents as Tools” 模式：主 Agent 保持最终控制权，专家 Agent 提供各自结果。

如何设计一个好的 Subagent？

1) 职责要窄

不要创建“全能 subagent”。
好的 subagent 应该像一个明确岗位：

只读探索
安全审查
测试分析
数据检索
需求澄清

职责越窄，越容易写清楚提示词、权限和验收标准。

2) Description 要具体

Claude Code 和 OpenAI Agents 都依赖描述来决定何时调用/移交。
描述要写清楚触发场景。

不推荐：

description: Helps with code.

3) 权限要最小化

探索 Agent 尽量只读。
测试 Agent 可以运行测试，但不一定能改文件。
部署 Agent 才需要触达发布系统，并且最好加人工确认。

4) 输出要结构化

Subagent 的输出应该方便主 Agent 消化。

推荐格式：

## Findings

- [结论 1]
- [结论 2]

## Evidence

- [文件/命令/来源]

## Recommended Next Step

[建议主 Agent 做什么]

5) 不要过早拆分

OpenAI 官方文档也强调：能用一个 Agent 清楚完成时，不要急着拆。
只有当任务需要不同工具、不同权限、不同上下文或不同策略时，再引入 subagent。

Subagent、Skill、MCP、RAG 的关系

这些概念经常一起出现，但解决的问题不同：

概念	解决什么问题	典型作用
Subagent	谁来做子任务	多 Agent 分工协作
Skill	怎么做某类任务	可复用 SOP 和领域知识
MCP	怎么接外部工具	标准化工具/资源调用
RAG	知识从哪里来	检索增强生成
Prompt	怎么约束模型行为	角色、格式、边界

一个完整系统可能是这样：

主 Agent 接收任务
Skill 定义工作流
Subagent 分工执行
MCP 调用工具
RAG 提供知识上下文
Prompt 控制输出格式和边界

Multi-Agents 与 Agent Teams：概念辨析

辨析两个经常混用的术语：Multi-Agents（多智能体系统） 与 Agent Teams（智能体团队）。理解这两个概念的边界，有助于在选型时判断自己需要的是“松散协作”还是“有组织的团队”。

术语来源

Multi-Agent Systems (MAS)：学术界与工程界的通用术语，泛指多个自主 agent 共存的系统。agent 之间可以有各自的目标，甚至存在竞争关系，协调方式可以是市场式、拍卖式或无中心协商。
Agent Teams：MAS 的一种特化形态。强调成员围绕同一个团队目标协作，有明确的角色分工和协调机制（通常是协调者或固定流程）。

核心区别

维度	Multi-Agents	Agent Teams
目标关系	各 agent 目标可独立、可竞争	共享同一团队目标
协调机制	松散、市场式、可无中心	有明确协调者或固定流程
角色定义	灵活、可临时组合	固定岗位、有角色感
上下文共享	强调隔离	可共享部分状态（如团队黑板）
失败语义	单个 agent 失败影响局部	成员失败影响整体交付

包含关系

所有 Agent Team 都是 Multi-Agent System，反之不成立。Team 在 MAS 之上叠加了“共同目标 + 角色分工 + 协调机制”三个约束，是一种更结构化的子集。

graph TD
    M["Multi-Agent Systems (通用)"]
    T["Agent Teams (特化)"]
    M --> T

框架落点举例

不同框架对这两个概念的侧重不同，选型时可参考：

AutoGen 0.4：Team 是一等概念（RoundRobinTeam / SelectorTeam / MagenticOneTeam / SwarmTeam），是典型的 Team 范式实现。
CrewAI：Crew = Team，Agent = 成员，Task = 分工，天然贴合 Team 模型。
LangGraph：通过 graph 编排多 agent，偏 MAS 风格，supervisor / hierarchical 是可选 pattern 而非强制。
OpenAI Agents SDK：orchestration（handoffs / agents-as-tools），偏 MAS 通用编排，不强制 team 概念。
Claude Code Subagent：MAS 中 “agents as tools” 的开发场景特化，专家 subagent 无共同目标，由主 agent 统一编排。

如何选择

落地时可以用一句话判据：

“成员是否为同一个可交付物负责？”

是 → 倾向 Agent Teams：共享单一交付目标 + 稳定角色分工，适合有明确产物的工作流（如交付一个功能、一份报告）。
否 → 倾向 Multi-Agents：多目标、松散协作、灵活组合，适合客服分流、多意图处理、可插拔专家。

落地建议

如果你想在项目里引入 subagent，可以从这个顺序开始：

先找出最容易污染上下文的任务，比如代码探索、资料检索、测试分析
把这些任务拆成只读 subagent
给每个 subagent 写清楚 description、工具权限和输出格式
让主 Agent 只接收摘要，不接收全部中间过程
再逐步引入并行 subagent 和 handoff 模式

最推荐的第一个 subagent 是：只读代码探索 Agent。
它风险低、收益高，能显著减少主 Agent 的上下文负担。

总结

Subagent 不是“更多 Agent 就更智能”，而是一次职责拆分。
它让复杂任务变成多个可控、可审计、可并行的子任务。

你可以记住这句话：

Claude Code subagent 更强调开发任务中的上下文隔离和任务委派
OpenAI Agents 更强调 handoff 和 agents-as-tools 的通用编排模式
好的 subagent 应该职责窄、权限小、输出结构化

当任务开始变长、工具变多、上下文变乱时，就是引入 subagent 的好时机。

一文读懂什么是 Subagent

一文读懂什么是 Subagent

什么是Subagent ？

为什么需要 Subagent？

1) 上下文污染

2) 职责不清

3) 工具权限过大

4) 并行能力不足

如何使用Subagents

Claude Code 中的 Subagent

Claude Code 自定义 Subagent 示例

Claude Code中Subagent配置字段

OpenCode中的Subagent

OpenCode自定义 Subagent 示例

Cursor中的Subagent

Cursor中使用Subagent示例

Cursor中Subagent配置字段

使用子代理Subagents注意点

Subagent不会自动继承“主对话已经使用过的 skill 上下文”。

子代理嵌套调用深度为1

多Subagents设计模式

模式一 集中式编排

模式二 状态驱动的Agent切换Handoff

Claude Code 示例

OpenCode 示例

Cursor 示例

模式三 路由器模式 Router

三种模式对比

Subagent 的多 Agent 协同案例

案例一：代码变更流水线

案例二：企业客服分流

案例三：内容生产工作流

如何设计一个好的 Subagent？

1) 职责要窄

2) Description 要具体

3) 权限要最小化

4) 输出要结构化

5) 不要过早拆分

Subagent、Skill、MCP、RAG 的关系

Multi-Agents 与 Agent Teams：概念辨析

术语来源

核心区别

包含关系

框架落点举例

如何选择

落地建议

总结

参考资料

千问大模型

热门文章

最新文章

相关电子书

模式一集中式编排

模式二状态驱动的Agent切换Handoff

模式三路由器模式 Router