跳转至

Subagent 子智能体体系

独立子任务与继承式子任务、父子会话树、后台非阻塞并发与精准消息路由。

在复杂项目中，单个 Agent 会话的上下文窗口非常宝贵。如果将庞大的调研、代码审查或批量检索任务全部堆积在主会话中，不仅会导致上下文迅速耗尽，还会引入严重的信息噪音。

DSH 构建了一套工业级的 Subagent（子智能体）委托体系。

核心文件速查

路径 职责 重要度
packages/subagent/subagent/src/index.ts Subagent 服务定义与 Provider 注册表 ⭐⭐⭐
packages/subagent/subagent-spawn-in-process/ 独立干净会话子 Agent 驱动器 (subagent) ⭐⭐⭐
packages/subagent/subagent-fork-in-process/ 会话分叉继承驱动器 (subagent_fork) ⭐⭐⭐
packages/subagent/tool-subagent/src/index.ts 暴露给主模型的 Subagent 工具集合 ⭐⭐⭐

两种子任务范式：subagent vs subagent_fork

DSH 清晰划分了两种子任务场景：

┌────────────────────────────────────────────────────────────┐
│ 1. subagent (全新独立上下文)                                │
│    - 创建一个没有任何父会话历史的全新 Agent 实例             │
│    - 仅接收独立的 prompt 指令                               │
│    - 适用场景: 独立模块调研、外部文档检索、完全解耦的子模块实现│
└────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────┐
│ 2. subagent_fork (会话分叉继承)                             │
│    - 继承父会话截至上一轮的所有历史事件与对话上下文         │
│    - 子任务在这个丰富背景下执行专项分析                     │
│    - 适用场景: 针对刚刚讨论的代码做 Review、分支方案探索     │
└────────────────────────────────────────────────────────────┘

后台非阻塞委托与 Inbox 结算

在 DSH 中，主 Agent 调用 subagent 或 subagent_fork 默认在 后台异步运行（run_in_background: true）。

Main Agent                     Runtime                      Subagent (Worker)
    │                             │                                 │
    ├─── tool/call: subagent ────►│                                 │
    │    (Returns subagent_id)    ├─── Spawn Isolated Context ─────►│
    │                             │                                 │ (Executing in background)
    ├─── Continue Other Tasks ───►│                                 │
    │                             │                                 │
    │                             │◄── Run Settled (Final Answer) ──┤
    │                             │                                 │
    │◄── Inbox Notice Delivered ──┤
    │    (Subagent finished)      │
    │                             │
    ├─── Process Child Outcome ──►│
  1. 主 Agent 发起调用后立即获得一个持久化的 subagent_id，无需原地同步阻塞等待；
  2. 主 Agent 可以在同一个 Turn 内并发派发多个 Subagent，并继续执行其他独立任务；
  3. 子任务执行完成后，Runtime 会将包含最终结论的通知事件投递到主 Agent 的 Inbox 中；
  4. 主 Agent 还可以通过 send_message 开启后续多轮对话，或通过 interrupt_agent 随时打断耗时任务。

父子会话树与跨层级发现

DSH 的会话注册表支持树形遍历： - list_agents(scope: 'children')：仅发现当前 Agent 的直接子任务（深度为 1）； - list_agents(scope: 'descendants')：以稳定的前序遍历发现整个树形结构下的所有后代子任务。

本章思考与自测

  1. 思考题：为什么 subagent_fork 只继承已完成的历史轮次，而不继承当前正在执行的（in-flight）轮次？
  2. 自测题：在 DSH 中，子智能体（Subagent）产生的所有工具调用和中间思考过程，会直接追加到父会话的 SessionEvent 日志中吗？为什么这种设计保护了主会话的上下文？