第15讲 · Subagent——可续跑的后台子代理

《DeepSeek Harness 从上手到精通》系列 · 第五阶多智能体编排篇

🎯 目标：掌握子代理的创建、监督与协作难度 ★★☆ ⏱ 约 30 分钟前置：第 1–5 讲 Agent 基础

单一 agent 一次对话能做的有限。当任务可以拆成几件互不依赖的事，让主 agent 派生几个后台子代理分头干、再汇总，效率直接起飞。这就是 subagent。系列基于 deepseek-ai/deepseek-harness（0.1.0-rc.5，MIT），preview 阶段以官方 README 为准。

一、subagent 与 subagent_fork

dsh 提供两个派生子代理的方式：

subagent：派生一个后台运行的子代理，不阻塞主 agent，主 agent 可继续干活或等待它回报；
subagent_fork：从当前上下文克隆一份分支，让子代理在独立副本上实验，不污染主会话（类似第 2 讲的 fork 思路）。

Subagent 编排示意 — **图 1** 主 agent 派生多个后台子代理并行调研，结果回传汇总。

二、结构化控制：send_message / list_agents / interrupt_agent

子代理不是"放了就不管"，dsh 给你一套结构化控制工具：

工具	作用
`send_message`	向指定子代理发指令 / 追问
`list_agents`	查看当前所有子代理及其状态
`interrupt_agent`	中断某个失控或跑偏的子代理

子代理有独立的作用域注册表（呼应第 12 讲）：派生时只给它这次任务需要的工具，既安全又让模型调用更准。

三、subagent seam 的可替换性

和 fs、llm 一样，subagent 也是一个 seam（第 7 讲概念）。默认实现是在本进程里新建子 agent；但你也可以把"委派子代理"这件事换成外部产品——比如通过第 3 讲讲的 ACP，把活派给另一个 dsh 实例、甚至另一个 Agent 后端。

这意味着同一条 subagent 调用，底下可以是本地线程、也可以是跨网络的 Agent 服务——换 Provider 即可，编排逻辑不变。

四、何时用、何时别用（反模式警示）

该用：任务能拆成互不依赖的子任务，且每个子任务较重（调研、长篇生成、并行检索）。

别用（反模式）：

一件事一句话就能解决，却硬派子代理——多一层编排只会增加延迟和出错面；
子任务强依赖彼此输出——那应走第 16 讲的 workflow 流水线，而非 subagent；
子代理数量失控——派太多会撑爆上下文、互相抢工具。

五、动手练习：主 agent 派 2 个子代理并行调研 → 汇总

给主 agent 一个明确意图，让它派生两个后台子代理分别调研、最后汇总：

# 在 Web UI 消息框输入（示意意图，具体工具名以 tool-catalog 为准）
请并行做两件事：
1) 派生子代理 A：调研 DeepSeek 最新开源动态；
2) 派生子代理 B：调研 Agent 编排的主流方案；
两者都完成后，由你汇总成一份对比简报。

期间用 list_agents 观察两个子代理的状态，确认它们并行推进、最终由主 agent 汇总成简报，本讲产出即达成。

六、常见坑

子代理跑飞：忘了给它受限 scope，它调了不该调的工具——派生时收紧作用域；
主 agent 不等结果：子代理是后台的，主 agent 可能提前总结——用 send_message 收口或显式等待；
上下文膨胀：派太多子代理，每个的产出都回传，撑爆窗口——只回传精炼结论；
混淆 subagent 与 workflow：有强依赖顺序就别用 subagent，第 16 讲见分晓。

七、官方文档对应章节

docs/ 中 subagent、agents、seam 相关章节
第 7 讲"能力 Seam"理解 subagent 的可替换性
第 3 讲 ACP，了解"委派给外部 Agent 后端"的落地方式

本讲内容基于 DeepSeek Harness 官方文档与项目源码整理，仅供学习参考，具体命令与配置请以官方最新版本为准。系列文章配合源码仓库食用效果更佳：https://github.com/deepseek-ai/deepseek-harness

咨询 DeepSeek Harness 相关问题，请加微信：A0qingfengyuan_01

个人观点，仅供参考，如有不对之处，请多包涵，欢迎指出。本文由 AI 协助完成！

DeepSeek Harness 教程 · 第15讲 Subagent