跳到主要内容

5 分钟从入门到避坑：Sub-Agent 完全指南

· 阅读需 5 分钟

基于《多Sub-Agent官方建议与使用场景》提炼的核心内容，便于快速查阅与决策。
制定日期：2026-03-09
最后修订：2026-03-09

30 秒速览​

  • Sub-Agent 是什么：长任务卸载到子会话，主会话立即响应，子任务完成后通过 announce 回传
  • 何时用：长任务、并行处理、成本分层、会话隔离 → 用 Sub-Agent；类型少、小批量、优先降运维 → 可考虑单 Agent + Skills
  • 与 Skills 关系：互补，非二选一；Sub-Agent 管会话与执行，Skills 管能力与编排
  • 关键配置：model（便宜模型省钱）、runTimeoutSeconds（300–900）、maxSpawnDepth（推荐 2）
  • 必知限制：announce 为 best-effort；子 Agent 仅注入 AGENTS.md + TOOLS.md；超时≠归档

快速决策树​

先看这张表，再决定用 Sub-Agent 还是 Skills：

你的需求更合适的做法
多源、多类型、批量处理，主会话需快速响应、并行抽取主 Agent + 多 Sub-Agent
类型少、单条/小批量、对延迟不敏感、优先降低运维单 Agent + 多 Skills
先验证流程再上 Sub-Agent单 Agent + Skills 跑通 → 再按类型拆成 Sub-Agent

一、官方定位（一句话）​

Sub-Agent 是「长任务卸载、主会话不卡顿」的标准手段：繁重工作派发到子会话，主会话立即得到反馈；子任务完成后通过 announce 回传摘要；可为子智能体配置更便宜模型以控制成本。

二、推荐 vs 不推荐​

推荐与不推荐的适用场景对照：

推荐使用 Sub-Agent不推荐替代
长任务 / 繁重工作用「单 Agent + 多 Skills」替代 Sub-Agent
按任务类型派发（招投标、企业、政策等）Skills 不提供独立会话、异步回传、并行子任务
需要并行执行、提高吞吐
成本分层（主用强模型编排，子用便宜模型干活）
会话与上下文隔离

三、Sub-Agent 与 Skills 的关系​

层级职责
Sub-Agent会话与执行隔离层：独立 session、异步 announce、并行子任务、可配便宜模型
Skills能力描述与编排层：教 Agent 何时用、怎么用工具与流程

互补而非二选一：主 Agent 与各 Sub-Agent 都可挂载 Skills；主 Agent 负责派发与汇总，Sub-Agent 在各自会话中按 Skill 执行具体逻辑。

四、核心配置参数速查​

4.1 全局默认 agents.defaults.subagents​

参数作用建议
model子任务默认模型设为更便宜模型以省成本
runTimeoutSeconds子任务超时（秒）建议 300–900，避免无限挂起
maxChildrenPerAgent每会话最多活跃子会话数默认 5，范围 1–20
maxConcurrent全局 subagent 并发上限默认 8
archiveAfterMinutes子会话自动归档时间默认 60 分钟
maxSpawnDepth嵌套深度推荐 2（main→编排者→叶子）

最小可用示例：

agents:
  defaults:
    subagents:
      model: "gpt-4o-mini"        # 子任务用便宜模型
      runTimeoutSeconds: 600       # 10 分钟超时
      maxSpawnDepth: 2

4.2 跨 Agent 派发权限​

  • 在被派发的子 Agent 上配置 allowAgents: ["主Agent的id"]
  • 主 Agent 无需「注册」可派发列表；权限只在子 Agent 侧声明

4.3 sessions_spawn 工具要点​

  • 非阻塞：调用立即返回 { status: "accepted", runId, childSessionKey }
  • 回传：子任务完成后通过 announce 回传（best-effort，Gateway 重启可能丢失）
  • 必填：task；可选：agentId、model、runTimeoutSeconds、cleanup 等

五、重要限制与边界​

  • announce 为 best-effort：关键结果可让主 Agent 用 sessions_history 或 transcript 做二次拉取
  • 子 Agent 上下文：仅注入 AGENTS.md + TOOLS.md（无 SOUL、IDENTITY、USER 等）
  • runTimeoutSeconds：仅终止运行，不自动归档；归档由 archiveAfterMinutes 或 cleanup: "delete" 控制

六、常见坑​

坑点说明应对
announce 丢失Gateway 重启时 best-effort 回传可能丢失关键结果用 sessions_history 或 transcript 二次拉取
子 Agent 上下文不全只注入 AGENTS.md + TOOLS.md，无 SOUL、IDENTITY、USER把子任务所需信息显式写在 task 里
超时≠归档runTimeoutSeconds 只终止运行，不自动删会话用 archiveAfterMinutes 或 cleanup: "delete" 控制归档
权限配置错位主 Agent 派发失败在被派发的子 Agent 上配置 allowAgents: ["主Agent的id"]

七、选型建议速查（含典型场景）​

需求特点典型场景更合适的做法
多源、多类型、批量处理，主会话需快速响应、并行抽取招投标多源抽取、企业信息批量采集主 Agent + 多 Sub-Agent
类型少、单条/小批量、对延迟不敏感、优先降低运维单文档问答、简单分类单 Agent + 多 Skills
先验证流程再上 Sub-Agent从 0 到 1 搭建单 Agent + Skills 跑通 → 再按类型拆成 Sub-Agent

八、参考与下一步​

  • 完整版：《多Sub-Agent官方建议与使用场景》——看完速查后，可阅读完整版了解设计细节与更多场景
  • 官方文档：Sub-Agents、Configuration Reference