Agent与SubAgent深度解析：从创建到调度的全链路机制

2401_82819240

510人浏览 · 2026-07-19 15:37:52

2401_82819240 · 2026-07-19 15:37:52 发布

Agent与SubAgent深度解析：从创建到调度的全链路机制

你用过 Agent 吗？你知道 Agent 是怎么"自主决策"的吗？当 Agent 需要同时处理多个任务时，它是怎么创建 SubAgent、怎么传递上下文、怎么调度执行顺序的？

这篇文章从架构层面拆解 Agent 和 SubAgent 的完整工作机制——SubAgent 的三种创建方式、父子 Agent 的上下文传递逻辑、以及 Agent Loop 的五步调度循环。

一、先看清定位：Agent、SKILL、Tool 到底什么关系

很多人在用 Claude Code 时，对 Agent / SKILL / Tool 三个概念容易混淆。先明确它们的分工：

对比维度	Tool（工具）	SKILL（技能）	Agent（智能体）
核心定位	单一函数/API	封装好的知识包+工作流	自主决策的执行者
触发方式	模型通过 tool_call 调用	用户触发 / 场景匹配	主 Agent 委托 / 环境感知
能力边界	一次调用，一个结果	一组相关能力的集合	多步骤、动态编排、自我纠错
有没有"脑子"	无，纯执行	无，纯流程	有，能观察→评估→决策→执行
典型例子	`read_file()`、`search_code()`	`skill-creator`、`gold_price_skill`	Explore Agent、Plan Agent

💡 关键洞察：Agent 和 SKILL 的核心区别在于自主决策能力。SKILL 是被动的——用户说做什么就做什么；Agent 是主动的——它收到目标后，自己规划路径、选择工具、验证结果。

二、SubAgent 的创建方式

当你和 Claude Code 对话时，它是一个主 Agent。当任务复杂到需要拆解并行处理时，主 Agent 会创建 SubAgent（子智能体）。

SubAgent 有三种创建路径：

2.1 方式一：通过 Agent 工具创建（Claude Code 原生方式）

这是最直接的方式。主 Agent 调用 Agent 工具来 spawn 一个 SubAgent：

{
 "tool": "Agent",
 "parameters": {
 "description": "搜索并分析认证相关代码",
 "prompt": "请在项目中找到所有与用户认证相关的代码文件，分析认证流程，列出每个文件的作用和关键函数。重点关注：登录、注册、token刷新、权限校验。",
 "subagent_type": "Explore",
 "run_in_background": true
 }
}

这个调用的核心字段：

description（必填）：3-5个词简短描述 SubAgent 要做什么，用于主 Agent 在日志和任务列表中快速识别
prompt（必填）：SubAgent 收到的完整指令，包含任务目标、期望输出格式、约束条件。这是上下文传递的核心载体
subagent_type（可选）：专用 Agent 类型，不同预设类型有不同能力：
general-purpose：全功能（默认）
Explore：只读探索，擅长搜索和代码分析
Plan：设计方案，输出计划文档
claude-code-guide：回答 Claude Code 相关问题
run_in_background（可选）：true → 异步执行，主 Agent 不等待；false/不传 → 同步执行，主 Agent 等待 SubAgent 完成后才继续
isolation（可选）："worktree" → 在临时 git worktree 中运行，完全隔离文件系统；不传 → 共享工作目录

2.2 方式二：通过 Task 工具创建（任务队列方式）

某些系统中，使用 Task 工具创建 structured task，相当于一种轻量级的 SubAgent 编排：

{
 "tool": "TaskCreate",
 "parameters": {
 "subject": "修复登录页面的认证bug",
 "description": "用户反馈登录后偶尔返回401错误。需要排查：1. token刷新时机 2. 并发请求导致token覆盖 3. 检查axios拦截器逻辑。修复后运行测试验证。",
 "activeForm": "修复认证bug中"
 }
}

Task 与 Agent 的区别：
- Agent → 自主执行的独立进程，有完整的思考-行动循环
- Task → 结构化的待办项，由主 Agent 统一执行和管理
- Agent 能自己决策工具调用链，Task 只是一个目标描述

2.3 方式三：通过 SKILL 间接创建

当 SKILL 内部定义了多步骤工作流，Claude Code 可能会为其中的子步骤自动创建 SubAgent：

用户调用 SKILL（如 paper_analyzer_skill）
SKILL.md 描述了一个多步骤分析流程
主 Agent 解析 SKILL 后发现可以并行
自动创建 SubAgent A：分析论文结构
自动创建 SubAgent B：提取实验数据
自动创建 SubAgent C：评估创新贡献
主 Agent 汇总三个 SubAgent 的结果，生成最终分析报告

💡 关键洞察：SubAgent 不一定由用户显式创建。当 Claude Code 判断任务可以并行拆解时，会自动 spawn SubAgent。这是 Agent 自主决策能力的核心体现——它能自己判断"这个任务太大，我需要帮手"。

三、主 Agent 与 SubAgent 的交互逻辑

3.1 任务委托的完整流程

SubAgent 被创建后，主 Agent 和 SubAgent 之间的交互遵循清晰的生命周期：

主 Agent 规划任务，决定创建 SubAgent
主 Agent 构造 prompt，通过 Agent 工具创建 SubAgent
SubAgent 收到 prompt，开始独立运行（自己的 Agent Loop）
SubAgent 完成后，将结构化结果返回给主 Agent
主 Agent 读取结果，决定下一步（整合 / 深入 / 创建更多 SubAgent）

3.2 上下文传递机制：什么传，什么不传

这是最容易被误解的地方。SubAgent 不会自动继承主 Agent 的完整对话历史。

SubAgent 收到的内容（通过 prompt 参数）：
- 任务描述和目标
- 明确的约束条件和期望格式
- 关键上下文信息（文件路径、依赖关系等）
- 可用的工具列表（根据 subagent_type 决定）

SubAgent 收不到的内容：
- 主 Agent 的完整对话历史
- 之前的 tool_call 执行结果
- 用户的原始输入（除非主 Agent 在 prompt 中传递）
- 主 Agent 的思考过程（thinking）
- Memory 文件内容（除非 prompt 中显式引用）

为什么这样设计：
- 控制 SubAgent 的上下文窗口大小
- 减少无关信息的干扰
- 安全隔离：SubAgent 不需要知道你之前的对话
- 性能：更少的 token 消耗

主 Agent 构造 prompt 的策略：

明确目标，而非步骤 — 差："先搜索文件A，再读文件B，然后分析..."；好："分析认证系统的架构，找出所有安全漏洞"
给出上下文，但不给全部历史 — 差：粘贴整个之前的对话记录；好：提取关键信息——"我们在重构 auth 模块，已知问题有 X 和 Y"
指定输出格式 — "输出 Markdown 格式，包含：文件列表、函数签名、调用关系"
设置边界 — "只搜索 src/auth/ 目录，忽略 test/ 目录"

3.3 环境隔离级别

Claude Code 提供两种级别的工作环境隔离：

Level 1：共享环境（默认）
- 同一个工作目录，主 Agent 和 SubAgent 共享文件系统、git 状态、环境变量
- 风险：SubAgent 可能修改文件，影响主 Agent 的后续判断

Level 2：Worktree 隔离（isolation: "worktree"）
- SubAgent 在 git worktree 副本上操作
- 主 Agent 的工作区不受影响
- 如果 SubAgent 没做修改，worktree 自动清理
- 如果做了修改，变更保留在独立分支上

3.4 结果回传与同步机制

同步模式（run_in_background: false）：
- 主 Agent 调用 → 阻塞等待 → 收到结果 → 继续
- 适用：结果直接影响下一步决策
- 例：先搜索代码 → 根据搜索结果决定怎么改

异步模式（run_in_background: true）：
- 主 Agent 调用 → 立即返回（返回 task_id）→ 继续其他工作 → 收到通知 → 取回结果
- 适用：多个独立任务并行
- 例：同时搜索前端代码、后端代码、配置文件

主 Agent 取回结果的两种方式：
1. 等待通知（推荐）：SubAgent 完成后自动通知主 Agent
2. 轮询检查：通过 TaskOutput 工具主动查询

注意：SubAgent 的结果是结构化的文本。它不是通过"对话"方式返回给主 Agent，而是作为一个工具调用的返回值。主 Agent 像读工具输出一样读取和解析 SubAgent 的返回结果。

四、Agent Loop 调度机制

4.1 Agent Loop 的五步核心循环

每个 Agent（无论是主 Agent 还是 SubAgent）都运行在同一个核心循环中：

Plan（规划）：分析当前状态（已经完成了什么？还剩什么？），如果涉及 SubAgent 决定是创建新的还是等待已有的，决定下一个动作（调哪个工具？创建 SubAgent？返回结果？），关键决策：是否拆解为子任务并行？
Execute（执行）：调用工具（read_file、search_code 等），创建 SubAgent（Agent 工具调用），运行代码（Bash/ExecuteCode），每次执行完后进入 Observe 阶段
Observe（观察）：读取工具返回值，读取 SubAgent 返回结果，分析错误信息，理解执行效果
Decide（判断）：任务目标达成了吗？需要重试吗？是否需要补充信息？结果足够让用户满意吗？
循环：如果"继续" → 回到 Plan，用新的状态重新规划；如果"完成" → 整理结果，返回给主 Agent 或用户

4.2 任务队列与并行 SubAgent 调度

当主 Agent 需要同时运行多个 SubAgent 时，调度策略如下：

以3个 SubAgent 同时启动为例：

t0: 同时创建 A、B、C（全部 run_in_background: true）
t0: 收到三个 task_id，记录到任务列表
t0: 主 Agent 可以继续执行自己的任务（不阻塞）
t1: 收到通知 → SubAgent C 完成 → 取回结果，并入主的上下文
t2: 收到通知 → SubAgent A 完成 → 取回结果 → 发现 A 的结果揭示了一个新问题 → 创建 SubAgent D 去调查该问题
t3: 收到通知 → SubAgent B 完成 → 取回结果 → 所有结果收集完毕 → 整合四个 SubAgent 的结果 → 生成最终回复给用户

💡 关键洞察：主 Agent 不是"等待所有 SubAgent 完成后再行动"的。它可以边等边做——收到一个完成一个，甚至根据某个 SubAgent 的结果动态决定是否创建新的 SubAgent。

4.3 SubAgent 间的依赖管理

模式 1：完全并行（无依赖）

三个 SubAgent 互不依赖，同时启动，各自独立完成，主 Agent 汇总结果。
- SubAgent A：分析前端代码
- SubAgent B：分析后端代码
- SubAgent C：分析数据库Schema

模式 2：串行依赖链

SubAgent A：搜索所有相关文件
→ SubAgent B：分析 A 找到的文件（A 的结果作为 B 的输入）
→ SubAgent C：根据 B 的分析生成重构方案（B 的分析结果作为 C 的输入）

主 Agent 必须：启动 A → 等 A 完成 → 用 A 结果启动 B → ...

模式 3：混合依赖

A 和 C 可以并行启动
B 必须等 A 完成
D 必须等 C 完成
E 必须等 B 和 D 都完成

这是最复杂的场景，实际中最常见。

4.4 Loop 中的关键决策点

决策 1：自己做 vs 委托 SubAgent？

自己做的情况：任务简单（单个文件读取、简单搜索）、需要即时反馈、步骤间有依赖不适合并行

委托 SubAgent 的情况：任务可以独立完成、多个任务可以并行、任务量大需要上下文隔离、需要专用的 Agent 能力（如 Explore 类型）

决策 2：同步 vs 异步？

同步（run_in_background: false）：SubAgent 结果影响下一步决策、有严格的执行顺序要求

异步（run_in_background: true）：多个独立任务、不依赖 SubAgent 结果就能继续自己的事

决策 3：何时终止循环？

终止条件：目标已达成（最理想）、循环次数达到上限、结果质量已无法再提升、用户中断、遇到不可恢复的错误

4.5 超时、重试与容错

超时处理： 每个 SubAgent 有默认超时时间，超时后主 Agent 收到超时通知，可以选择重试 / 换策略 / 跳过该结果

部分完成重试策略：
- SubAgent 返回不完整结果 → 主 Agent 用更具体的 prompt 重新创建
- SubAgent 遇到工具错误 → 调整工具集后重试
- 多次失败 → 主 Agent 自己完成该子任务（降级策略）

错误类型与处理：

错误类型	主 Agent 的处理方式
SubAgent 超时	拆分任务、缩小范围后重试
工具不可用	检查工具配置、用替代工具
返回格式不符合预期	用更详细的 prompt 重新创建
权限不足	向用户申请权限后再创建
资源耗尽	串行化部分并行任务

五、实战：多 SubAgent 并行代码审查

用一个完整例子展示上述所有机制的串联：

场景：用户说 "帮我全面审查这个项目的代码质量"

Step 1 - Plan（规划）：任务分析：代码审查 = 结构分析 + 安全审查 + 性能审查 + 规范检查。决策：四个方向独立，可以并行。→ 创建 4 个 Explore 类型 SubAgent

Step 2 - Execute（执行 - 并行创建）：
- SubAgent A：分析项目代码结构和模块依赖
- SubAgent B：审查安全漏洞（注入、泄漏、权限）
- SubAgent C：审查性能问题（N+1查询、内存泄漏、不必要的重渲染）
- SubAgent D：检查代码规范（命名、注释、错误处理、测试覆盖）
- 四个全部 run_in_background: true

Step 3 - Observe（观察 - 逐个接收）：
- SubAgent D 最先完成 → 读取结果，记录
- SubAgent A 完成 → 读取结果，发现循环依赖问题
- SubAgent B 完成 → 读取结果，发现3个潜在安全问题
- SubAgent C 完成 → 读取结果，发现2个性能瓶颈

Step 4 - Decide（判断）：B 发现了安全问题需要深入确认 → 创建 SubAgent E 对3个安全问题逐个验证 → 等 E 完成 → 确认2个真问题、1个误报

Step 5 - 整合输出：

代码审查报告

一、架构问题（来自 SubAgent A）
 - 发现1个循环依赖

二、安全问题（来自 SubAgent B + E）
 - XSS 漏洞：2处
 - 密钥硬编码：1处

三、性能问题（来自 SubAgent C）
 - N+1查询：1处
 - 缺少组件懒加载：1处

四、规范问题（来自 SubAgent D）
 - 缺少错误处理：5处
 - 测试覆盖率不足：3个模块

主 Agent 将这个结构化的报告返回给用户。

六、最佳实践：让 Agent 和 SubAgent 稳定发挥

prompt 是最重要的接口：SubAgent 只能通过 prompt 理解任务。主 Agent 构造 prompt 时要：说清楚目标而非步骤（让 SubAgent 自己规划）、给出关键上下文（文件路径、已知约束）、指定期望的输出格式、给出判断标准（什么算"完成"）
粒度适中：太粗 → SubAgent 理解困难，容易出错；太细 → 失去 SubAgent 的自主决策优势。好的粒度："分析 src/auth/ 下的认证逻辑"；太粗："审查整个项目"；太细："读 src/auth/login.ts 第 42 行"
并行优先，依赖显式化：能并行的不要串行，有依赖的要说清楚——"等 SubAgent A 找到所有相关文件后，再把文件列表传给 SubAgent B 进行分析"
设置合理边界：文件范围（"只在 src/ 下搜索"）、时间上限（让 SubAgent 知道何时停止）、输出规模（限制结果长度，避免超出上下文）
利用专用 Agent 类型：Explore → 代码探索和分析（只读，更安全）；Plan → 技术方案设计；general-purpose → 需要执行的复杂任务。不要用 general-purpose 做纯搜索——Explore 更快更安全
始终验证 SubAgent 结果：SubAgent 也可能出错。主 Agent 收到结果后应该：检查完整性（所有要求都覆盖了吗？）、交叉验证（如果多个 SubAgent 有重叠范围，结果一致吗？）、兜底（关键发现要自己复查）

七、总结

Agent & SubAgent 全链路总结：

主 Agent 运行 Agent Loop（Plan → Execute → Observe → Decide → 循环），通过 Agent 工具创建 SubAgent
SubAgent 有独立循环，各自 Plan→Exec→Obs→Dec，完成后返回结构化结果
三层上下文传递：prompt 参数（主 Agent 精选的关键信息和任务描述）→ SubAgent 自身循环（执行过程中的内部积累）→ 返回结果（结构化的纯文本输出）
主 Agent 可以边等边做，根据 SubAgent 结果动态决策

掌握了这些，你就能理解 Claude Code 在后台是如何自主决策、创建帮手、调度执行的了。下次看到 Agent 自动创建 SubAgent 时，你就知道背后正在发生什么。