Subagent 实现：把脏活交给独立上下文

摘要有了任务规划，主 Agent 知道要做什么、做到哪一步。但复杂任务的执行细节仍然会污染主 history：网页正文、命令输出、文件搜索结果、报错日志都会被带进后续推理。Subagent 的价值。就是把这些局部探索放进独立上下文里完成，最终只把高密度回传主线。

标签Agent、Subagent、上下文隔离、并发、Tool Use

计划清楚了主上下文还是会变脏

使用者痛点 1：即使已经有了完整的任务计划。执行过程中仍然会把大量冗余信息塞进主历史，导致模型推理变慢、注意力被稀释。

假设使用者要求：

抓取三个网页。分别观点，最终比较差异，

如果主 Agent 直接调用 web_fetch每个网页几千字都会进入主 history；同理，遍历项目文件时的 grep 输出、报错日志也会不断堆积。说起来，对最终答案这些细节大多是中间材料，却占用了大量上下文空间。

痛点表现：

• 模型响应时间逐渐增长。其实，
• 关键信息在海量噪声中被淹没。
• 记忆压缩仍然需要先把“脏活”塞进去。再进行削减，成本高，怎么说呢，

解决思路：让主线只负责调度与汇总。所有局部探索交给独立的 Subagent 完成。

Subagent 是一个特殊工具

使用者痛点 2：缺少一种机制可以在同一程序内部安全地启动独立执行环境，而不必手动管理多个进程或线程。

在本项目中，子代理不是平级的“另一个人”。而是主 Agent 可以调用的特殊工具 dispatch_subagent。它的行为类似于 run_command/read_file但内部会启动一套独立的 AgentRunner.

主 Agent 发出 dispatch_subagent
↓ 创建子代理独立 history
↓ 子代理在自己的上下文里读文件、跑命令、抓网页
↓ 子代理产出 final summary
↓ 主 history 只收到一条 tool_result

dispatch_subagent 的参数设计

User Pain Point 3：任务描述不明确导致子代理无法自行完成工作，需要重复调试才能得到期望输出。

DispatchSubagentTool 参数虽少，却决定了子代理能否正确执行：

return tool_parameters_schema(
agent_type=StringSchema(
"子代理类型,必须是 description 中列出的可用类型之一"。enum=self._subagent_registry.names,),task=StringSchema(
"交代给小太监的差事,写清要做什么、希望返回什么格式的"
),purpose=StringSchema(
"一句话用途标签,仅用于终端打印",nullable=True,),)

• agent_type: 决定使用哪种子代理身份。
• task: 子代理唯一需要理解的指令。必须写成完整工单——目标、范围、输出格式、边界条件全部明确。
• purpose: 人类可读的日志标签，用于快速定位派遣来源。

阅读 agent/tools/dispatch.py 和 agent/subagents/registry.py。子代理工具白名单如何生效，回传三条关键结论，不要修改文件。其实，

看看 subagent 怎么实现的。话说回来，

独立 Runner 与工具白名单机制

User Pain Point 4：No‑SQL style “随意使用所有工具” 导致安全风险与不可预期行为。

`dispatch_subagent` 会根据 `agent_type` 找到对应 spec，并为子代理生成专属 ToolRegistry.

sub_registry = ToolRegistry
for tool_name in spec.tool_names:
tool = self._parent_registry.get
if tool is not None:
sub_registry.register
runner = self._runner_factory
history =
final = runner.step

• 独立 history → 防止跨层级污染。说起来，

身份模板与权限分离

User Pain Point 5：The same prompt is used for both role definition and permission control,making it easy for model to overstep boundaries.

• ID 模板存放在

  xiaohuangmen # 轻量只读
  sili_suitang # 只读文书
  dongchang_tanshi # 查访资料
  shangbao_dianbu # 盘点核验
  neiguan_yingzao # 可读写可执行
  

  ("run_command"。"web_fetch","load_skill","read_file","write_file","edit_file","glob","grep")
  

并发派遣机制

User Pain Point 6：The system lacks a clear way to run multiple independent subtasks in parallel without manual thread management.

• `dispatch_subagent` 被标记为 ``concurrency_safe``。
• `AgentRunner` 会在同一轮模型返回多个 ``dispatch_subagent`` 调用时通过线程池并行执行，并按原顺序填充结果。

派 A 读文件一
派 B 读文件二
派 C 读文件三
当模型一次性发出以上三条指令时它们将并行运行。从*注意*来看，如果任务本身更适合一次性命令。模型可能直接使用普通工具而非子代理，这也是合理选择。

# 小技巧：在提示中显式说明 “分别派三个子代理。各自处理一个文件，再汇果”，可以诱导模型走并发方法。

Subagent 最适合的场景

• A. 大规模只读探索： 读取多个文件、抓取网页或搜索项目结构，只需最终结论即可。
B. 边界明确的局部任务： 检查某两个模块是否注册了工具、整理几篇文档差异等，一次性完成后销毁即可。C. 可并行分支任务： 分别检查三个目录或三个网页，再由主 Agent 汇总。不适用场景： 需要长期协作、多轮交互或状态保持的角色，例如持续编码‑评审循环。这类需求应使用持久化角色而非一次性 Subagent。

如何判断一次派遣是否成功

# 检查技巧：打开 DEBUG 模式。可看到每个 Subagent 的完整历史记录保存方法，从而快速定位问题根源。L4 如果以上信号缺失。则说明模型走了普通工具方法，这不一定错误，只是策略选择不同罢了。

为什么 Subag​ent 不再派 Subag​ent?

User Pain Point 7: 递归调度容易导致不可控成本爆炸——难以追踪 token 消耗和错误来源，也容易产生无限循环。“层层派人”看似强大，却让程序失去结构化管理能力。为此白名单刻意剔除 ``dispatch_subagent``，保证单层调度 + 明确职责 + 可观测性 的设计原则得以贯彻。

# 小结图示： 主 Agent ──► dispatch_subag​ent ──► 子 Agent ──► summary 回传至 主 Agent **不** 再向下递归。

白名单比 Prompt 承诺更可靠 User Pain Point 8: 仅靠 Prompt 要求模型遵守权限容易失效——模型可能“忘记”自己不能写文件或者不能再派人。我们采用**代码约束**：

如果白名单里没有 write_file，则无法写入；没有 dispatch_subag​ent，则无法递归派遣。Prompt 用来表达职责与策略，而实际边界由 ToolRegistry 强制执行。这样即使模型尝试违背指令。也会因缺少对应接口而失败，从而提高程序安全性。在实际部署中，可每次调用是否符合预期白名单。