发布日期：2026-11-06 ｜ 数据截至 2026-11-06，来源为 DeepSeek Harness 官方文档（deepseek-harness.github.io）、GitHub 仓库及 v0.2.1-alpha.3 更新日志

DeepSeek Harness（DSH）的子智能体（Subagent）机制允许主 Agent 把任务拆分后委派给多个独立子 Agent，每个子 Agent 在自己的会话里完成工作，中间步骤不进入父级上下文，只把最终结果交回主 Agent。v0.2.1-alpha.3（2026 年 10 月 14 日）新增了子智能体独立 Agent Preset 支持：每个子 Agent 可以带自己专属的角色设定和工具清单派发出去，不再共用主 Agent 的配置，也不需要每次委派都复制粘贴一遍。本文覆盖 Subagent 的核心机制（spawn vs fork、agentPreset 字段、toolFilter 工具隔离）、三种典型分工场景的配置思路，以及 Agent Teams 实验性功能的适用边界，帮助开发者快速建立多 Agent 分工的完整认知。

Subagent 解决什么问题：从单体 Agent 到多 Agent 分工

单体 Agent 处理大型任务时碰到两道墙：上下文膨胀和串行等待。读几十个文件的细节会挤爆主对话的上下文窗口；任务逐个处理，前一个没完成后一个无法开始。

Subagent 的解法是：主 Agent 把一块独立工作"委派"给一个全新子 Agent，子 Agent 在自己的会话里完成工作，只把最终结果交回父级。好处是子 Agent 的中间步骤不进入父上下文——既节省 token，也让主上下文保持干净，不被调试日志和临时输出淹没。

在 DSH 里，多 Agent 协作的三个核心痛点对应三个解法：

痛点

解法

单个 Agent 上下文装不下

Subagent 分会话，中间步骤不回传

职责分不清，系统提示词混乱

每个子 Agent 绑定独立 Agent Preset

工具乱用，子 Agent 越权操作

toolFilter 划工具边界

Spawn vs Fork：先搞清楚两种子 Agent 的区别

DSH 的 Subagent 有两种创建方式，配置 Agent Preset 之前必须分清楚：

Spawn（新建子 Agent）：子 Agent 拥有全新会话，不继承父方上下文。这是唯一支持指定独立 agentPreset 的方式。适合需要明确角色边界的分工场景，比如"代码审查 Agent"和"文档生成 Agent"各自职责清晰。

Fork（派生子 Agent）：子 Agent 继承父方的活跃组装，包括工具集、系统提示词和当前上下文。Fork 不支持指定独立 agentPreset，省略时直接沿用父方的当前配置。适合需要父方上下文的场景，比如"继续处理这个文件的另一个任务分支"。

官方文档的核心接口定义：

interface SubagentStartRequest {
  /**
   * Independent preset id; omission joins the parent's current generation.
   * Requires a provider with capabilities.agentPreset that does not inherit
   * parent context.
   */
  readonly agentPreset?: string
  /** Content delivered as the child's user message. */
  readonly prompt: ContentBlock[]
  /** The spawning agent. */
  readonly parent: Agent
}

agentPreset 只在 spawn 时有效，fork 忽略这个字段。

v0.2.1-alpha.3 新增：子 Agent 独立 Preset 配置

这是这个版本最实用的多 Agent 更新。之前委派子任务时，子 Agent 的角色设定和工具清单要么跟着父方走，要么在每次委派时手动传入 prompt 覆盖——繁琐且容易漏项。

v0.2.1-alpha.3 把这件事系统化了：在 Agent Preset 里配好角色设定和工具清单，委派时直接指定 Preset ID，子 Agent 按这份配置启动，不需要在 prompt 里塞角色描述，也不会受父 Agent 配置影响。

在哪里配 Preset：设置 → Agent Preset，每个 Preset 包含：

  • 系统提示词（角色定义、行为边界、输出格式要求）

  • 工具清单（允许哪些工具、拒绝哪些工具）

  • 可选：模型指定（子 Agent 使用不同于父 Agent 的模型）

怎么在委派时指定：在标准模式下发出委派指令时，DSH 会展示可选的 Preset 列表，选择后该 Preset 随委派一起发出。子 Agent 启动时读取指定 Preset，不继承父方活跃配置。

toolFilter：给子 Agent 划工具边界

Agent Preset 解决角色定义问题，toolFilter 解决权限边界问题。

toolFilter 是在 Agent Preset 配置里针对每个工具的开关。配置逻辑直接：

  • 允许：子 Agent 可以调用该工具

  • 拒绝：子 Agent 调用该工具时直接被拦截，不会执行

常见的权限配置模式：

只读审查 Agent（代码审查、文档扫描）：

  • 允许：read_file、list_directory、search

  • 拒绝：write_file、edit_file、run_command

只写生成 Agent（文档生成、报告输出）：

  • 允许：write_file、read_file（读取上下文）

  • 拒绝：run_command、delete_file

执行 Agent（测试运行、构建验证）：

  • 允许：run_command、read_file

  • 拒绝：write_file（防止测试 Agent 意外修改源码）

配错 toolFilter 的典型后果：给只读 Agent 保留了 write_file，它会在分析代码时顺手"优化"文件——这类越权改动很难追溯，因为父 Agent 的上下文只看到最终结果，不看子 Agent 的中间步骤。

三种典型分工场景配置思路

场景一：代码审查 + 文档生成并行

目标：一个 Agent 读源码写审查报告，另一个 Agent 读源码更新 API 文档，两个任务并行不干扰。

配置要点：

  1. 创建两个 Preset：code-reviewer（只读工具）、doc-writer（读写文档目录，不写源码目录）

  2. 主 Agent 把"代码审查"委派给 spawn 子 Agent，指定 code-reviewer Preset

  3. 同时把"更新 API 文档"委派给另一个 spawn 子 Agent，指定 doc-writer Preset

  4. 两个子 Agent 并行跑，主 Agent 等待两个结果后汇总

关键配置：doc-writer 的 toolFilter 只允许写 docs/ 目录下的文件，拒绝写 src/ 目录，防止文档 Agent 误改源码。

场景二：数据分析 + 可视化分工

目标：一个 Agent 做数据清洗和统计计算，另一个 Agent 拿计算结果生成图表。

配置要点：

  1. data-analyst Preset：允许读数据文件、运行 Python 脚本、写临时结果文件

  2. chart-generator Preset：允许读临时结果文件、写图表输出目录，拒绝运行命令

  3. 主 Agent 先委派数据分析，拿到结果文件路径后再委派图表生成

  4. 两阶段串行，chart-generator 的 prompt 包含上一步的结果路径

场景三：多语言翻译并行

目标：把一份技术文档同时翻译成英文、日文、韩文。

配置要点：

  1. 创建通用 translator Preset，系统提示词里定义翻译风格和术语表

  2. 委派三个 spawn 子 Agent，各自带目标语言参数，共用同一个 Preset

  3. 三个子 Agent 完全并行，互不依赖

  4. 主 Agent 收到三份结果后做最后的格式整理

这个场景展示了 Preset 复用的价值：一份 Preset 配置，三个子 Agent 共用，改翻译规则只需改一处。

Agent Teams：实验性的持久多 Agent 协作

v0.2.1-alpha.3 在 Agent Preset 之外还有一个更进一步的机制：Agent Teams，官方标注为实验性功能。

Agent Teams 和 Subagent 的核心区别：

维度

Subagent

Agent Teams

生命周期

任务完成后释放

持久 roster，可持续接任务

通信方式

主 Agent 委派，子 Agent 返回结果

直接 inbox 消息，支持双向通信

状态管理

无状态，每次委派独立

有任务状态追踪

适用场景

一次性并行任务

长期运行的 Agent 团队

Agent Teams 通过显式启用 ctx.agentTeams 激活，在可继续 Subagent 之上提供持久成员名单（roster）和任务状态管理。适合"常驻 Agent 团队"场景，比如一个前端 Agent 和一个后端 Agent 长期协作，共享任务板，互相分派子任务。

实验性意味着：API 可能变化，生产环境谨慎引入，官方文档也明确标注了实验性。

用 list_agents 管理在线子 Agent

委派多个子 Agent 后，用内置工具查看运行状态：

在对话框输入：

list_agents

返回当前直接子级列表，每个子 Agent 的状态为 running（正在执行）或 inactive（已完成/暂停，可继续）。配合 Preset，你还能看到每个子 Agent 是哪个 Preset 配置启动的，方便追踪分工。

外部执行（通过 ACP、DSH SDK 等接口启动的子 Agent）携带 mode: 'external'，不能接受后续消息，也无法打开子会话，只能查看执行结果。

FAQ

Q：Agent Preset 和系统提示词有什么区别？ 系统提示词是给模型看的角色定义文本；Agent Preset 是一整套配置的打包，包含系统提示词、工具清单、可选的模型指定。系统提示词是 Preset 的一部分，Preset 是更高层的配置单元。

Q：子 Agent 的中间步骤会进入父 Agent 上下文吗？ 不会。子 Agent 在自己的会话里完成工作，只有最终输出（SubagentResult.output）回传给父 Agent。这是 DSH Subagent 的核心设计：父级上下文只看到结果，不看过程，所以父级的 token 消耗不随子任务复杂度线性增长。

Q：toolFilter 配置错了怎么修复？ 直接在 Agent Preset 设置里调整 toolFilter，保存后对新委派的子 Agent 立即生效。已经在跑的子 Agent 不受影响，它们按启动时的配置运行到结束。

Q：同一个 Preset 能同时用于多个子 Agent 吗？ 可以。Preset 是只读配置模板，多个子 Agent 可以引用同一个 Preset ID，各自独立运行，互不干扰。这也是场景三（多语言并行翻译）的基础。

Q：API 调用成本怎么算，子 Agent 的调用会合并计费吗？ 子 Agent 的每次模型调用按各自的 token 用量独立计费，不合并。多个子 Agent 并行时，总成本 ≈ 各子 Agent 成本之和。如果需要统一管控多模型 API 调用的用量和预算上限，可以通过七牛云 Token Plan（qiniu.com/ai/plan）的订阅制方案，月费即为硬上限，不会出现意外超额。

延伸阅读

  • DeepSeek Harness 官方文档（子代理章节）：deepseek-harness.github.io/deepseek-harness/reference/subsystems/subagent

  • DeepSeek Harness 架构参考：deepseek-harness.github.io/deepseek-harness/reference/

  • Agent Teams 子系统说明：github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/agent-team.zh.md