description: "面向用户与维护者的进程内 spawn subagent 后端说明，用于选择、配置或排查全新子级委派。" kind: "package-reference"

@qilin-agent/subagent-spawn-in-process

English | 中文

概述

dsh-subagent-spawn-in-process 是一个进程内 subagent 后端：它在当前进程中运行每个委派任务，子 agent（智能体）是一个全新子 Agent，复用宿主的 agent 工厂及 LLM（大语言模型）/工具服务。子 agent 以空对话开始，因此任务提示词必须自足；除非 request.agentOptions 覆盖，否则它继承父 agent 的工作目录、会话谱系、提供方、模型、推理强度与输出 token 上限。委派工具或 API 调用以 spawn 提供方名称找到它。需要成本最低的委派传输时选择它；需要子 agent 建立在父级已完成对话轮次之上时，请选择 fork 后端。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

在需要把工作委派给全新进程内子 agent 的组合中挂载此后端。常用配置路径很明确：加载 subagent 服务与本后端，再把 dsh-tool-subagent 之类的委派工具指向 spawn 提供方。

何时选择

当子 agent 不需要父级对话、且可以接受在本进程内运行时，选择 spawn 后端。当子 agent 必须建立在已完成父级轮次之上时——fork 后端会提供这些历史——或必须在本进程之外运行时（进程外后端提供此能力），请避免使用它。由于子 agent 默认继承父级的工作目录与 LLM 选择，自足的提示词会按原样生效。

最小配置

先加载 subagent 服务与本后端，再为每个目标配置一个委派工具。这是暴露由 spawn 支撑的 subagent 工具的最小组合：

- name: '@qilin-agent/subagent'
- name: '@qilin-agent/subagent-spawn-in-process'
- name: '@qilin-agent/tool-subagent'
  config:
    provider: spawn

| 字段 | 默认值 | 含义 | |---|---|---| | providerName | spawn | 注册到 ctx.subagents 的提供方名称 |

生成的配置目录是每个受支持字段及其 JSDoc 的穷尽式真源。

一次委派会做什么

一次工具调用创建后台子 agent 并立即返回子会话 ID。子级在自己的会话中工作，父级通过完成通知收到其最终答案。子级也可以通过 send_message 发送消息。被拒绝的启动不会留下已发布的子 agent；工作流等程序调用方可以直接等待 activation 的结果。

理解实现

本节说明提供方准备工作，以及由 subagent 服务拥有的 activation 生命周期。

设计理念

本后端注册提供方并准备全新子会话。dsh-subagent 拥有 activation 的深度检查、子 agent 创建、工具和 persona 设置、结构化输出、结果收集及资源释放；发布前的调用方信号取消创建，发布后的句柄通过 dispose() 取消并等待完全停稳。

源码地图

| 文件 | 职责 | |---|---| | src/index.ts | 提供方注册：Config schema、能力声明、prepareContinuable() |

运行流程

startActivation() 解析提供方并调用 prepareContinuable()，随后创建并发布子 agent。每次 activation 单独安装结构化输出。调用方可以等待 result，并通过 dispose() 等待整个子树完全停稳。

所有权与作用域

子 agent 获得全新的扁平注册作用域：父级工具限制与权限绝不会被导入，工具所施加的过滤属于组合而非父级派生授权。后端声明包括 agentOptions 在内的全部五项启动时能力，因为它控制子 agent 的创建窗口，可以逐一强制执行。

进一步探索

当包级约定不够用时阅读以下页面；它们从共享 subagent 模型进入兄弟后端与穷尽式配置。

• Subagent 子系统——启动请求、结果、实时运行与提供方约定。
• dsh-subagent-fork-in-process——以已完成父级轮次作初始内容的兄弟后端。
• dsh-tool-subagent——指向该提供方的面向模型委派工具。
• 生成配置目录——每个受支持配置字段及其源声明。

模型体验

子 agent 请求

模型看到什么

全新子 agent 逐字接收任务内容，作为新空对话中的唯一用户消息，默认使用父级提供方、模型、推理强度、输出 token 上限与工作目录。配置的 persona 会在子 agent 作用域中遮蔽全局提示词文本；工具过滤器会从其 schema、可执行工具查找与 PTC mode SDK 绑定中移除指定的全局工具，但保留独立注册的指导内容。不包含任何父级对话消息；过滤属于组合，而非继承的权限授予。

Token 影响

子 agent 会为全新的独立上下文与历史消耗 token，不复制任何父级历史 token。persona 会改变该子 agent 反复使用的提示词成本；工具过滤器会改变其 schema 或生成 SDK 的成本。

KV Cache 影响

子 agent 的请求缓存与父级相互独立。子 agent 历史仅追加；persona、工具过滤、生成 SDK、提供方或模型变化会建立不同的子 agent 前缀。

父级工具结果（间接）

模型看到什么

通过 dsh-tool-subagent，父级先收到子会话 ID，随后收到包含最终答案的完成通知。子级自行编写的消息通过 send_message 到达。子级内部工具调用保留在子会话中。

Token 影响

父级输入增加一个取决于数据的结果，并保留到上下文压缩（context compaction）为止。

KV Cache 影响

仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。

已知限制与延期工作

这些限制说明何时选择该后端是错误的；它们是当前包约束。

• 全新表示不含父级 transcript（文本记录）——子 agent 继承 cwd、谱系、提供方、模型、推理强度、输出 token 上限及显式配置的 persona/工具限制，但不继承父级的任何对话；需要已完成轮次上下文时，请使用 fork 后端。

开发备注

无。