一文读懂什么是 Subagent

一文读懂什么是 Subagent的重点在于把前置条件、操作顺序和容易误判的地方分清楚。

一文读懂什么是 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-reviewerdescription: 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 ReviewerYou are a focused code review subagent.## Responsibilities1. 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 practicesmode: subagentmodel: anthropic/claude-sonnet-4-20250514temperature: 0.1tools:write: falseedit: falsebash: false---You are in code review mode. Focus on:- Code quality and best practices- Potential bugs and edge cases- Performance implications- Security considerationsProvide 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-auditordescription: Security specialist. Use when implementing auth, payments, or handling sensitive data.model: inheritreadonly: true---You are a security expert auditing code for vulnerabilities.When invoked:1. Identify security-sensitive code paths2. Check for common vulnerabilities (injection, XSS, auth bypass)3. Verify secrets are not hardcoded4. Review input validation and sanitizationReport 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 TDA["Supervisor(主袋里)"]B1["SubAgent-A(搜索维度1)"]B2["SubAgent-B(搜索维度2)"]B3["SubAgent-C(搜索维度3)"]A-->B1A-->B2A-->B3

这种模式的优点：

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

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

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

graph LRA[billingAgent支付]B[triageAgent判断]C[refundAgent退款]A--handoff-->BB--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: implementerREASON: ...CONTEXT: ...NEXT_GOAL: ...ACCEPTANCE: ...

implementer 的行为约束：

你是 implementer agent。当收到 HANDOFF_TO: implementer 的上下文时：1. 接管任务所有权2. 不再询问 planner3. 直接进入实现与验证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，进行审查。"}}}

流程示例：

用户 -> plannerplanner 输出：HANDOFF_TO: implementerREASON: 方案已确认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.md2. 检查测试是否覆盖边界3. 判断是否可以交付

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

模式三 路由器模式 Router

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

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

三种模式对比

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

Subagent 的多 Agent 协同案例

下面看几个典型案例。

案例一：代码变更流水线

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

可以设计 4 个 subagent：

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

流程如下：

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

这个模式的好处是：

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

案例二：企业客服分流

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

可以设计：

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

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

flowchart TDU[用户问题] --> 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 TDTopic[文章主题] --> Research[Research Agent]Topic --> SEO[SEO Agent]Research --> Outline[Outline Agent]SEO --> OutlineOutline --> 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.

推荐：

description: Reviews code changes for correctness, security risks, and missing tests. Use after implementation or before opening a pull request.

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 TDM["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 的好时机。

参考资料

Claude Code: Create custom subagents Claude Blog: How and when to use subagents in Claude Code OpenAI API: Orchestration and handoffs OpenAI Agents SDK: Multi-agent orchestration OpenAI Agents SDK: Handoffs