多Agent协作揭秘:build-your-own-openclaw子智能体派发subagent_dispatch完整实现

原创2026-10-09 20:27:431,955 阅读
文章标签:示例工程教程人工智能AI AgentAI 应用Agent 工作流提示工程LLM 网关

多Agent协作揭秘:build-your-own-openclaw子智能体派发subagent_dispatch完整实现

在 build-your-own-openclaw 这个 18 步渐进式教程中,多Agent协作 是"自主与多智能体"阶段的核心能力。本文带你完整读懂它的子智能体派发机制:主智能体 Pickle 如何把任务分派给其他专业智能体,subagent_dispatch 工具又是如何通过事件总线(EventBus)把"派发—执行—取回结果"串成闭环的。

build-your-own-openclaw 多Agent协作教程封面:从零搭建你自己的AI智能体

为什么需要子智能体派发?

单个智能体什么都能干,但往往不够专业。build-your-own-openclaw 的思路是:让每个智能体专注一件事。

  • Pickle 🐱:直接和用户对话的"总指挥",处理日常任务
  • Cookie 🍪:记忆管理员,负责存储、整理和检索记忆

当 Pickle 收到"帮我读一下 README"这类请求时,它不需要亲自上阵,而是调用 subagent_dispatch 工具,把任务派给更合适的智能体。这就是多Agent协作中最经典的委托(delegation)模式。

两个智能体的定义都是纯 Markdown 文件,配置极简:

每个 AGENT.md 的 frontmatter 里声明了 name、description、llm 参数,正文就是系统提示词。description 字段很关键——它会被自动写进派发工具的说明里,帮助 LLM 判断"该派给谁"。

subagent_dispatch 工具是怎么创建的?

工具注册发生在每次新建会话时,见 _build_tools:

  • 工厂函数 create_subagent_dispatch_tool 会先扫描 agents 目录,动态发现所有可用智能体(排除当前智能体自己)
  • 把每个可派发智能体的 id 和 description 拼成一段 <available_agents> 清单,注入工具描述中
  • 用 enum 约束 agent_id 参数,LLM 只能选择真实存在的智能体
  • 如果当前只有一个智能体(没有可派发对象),工具直接不注册,返回 None

这个设计很巧妙:工具 schema 是动态生成的,新增一个 AGENT.md 文件,所有智能体立刻就能派活给它,零代码改动。

派发全流程:事件总线上的四步舞

subagent_dispatch 的核心不是"调用函数",而是基于 EventBus 的发布/订阅协作,完整流程如下:

  1. 发布:主智能体调用 subagent_dispatch(agent_id, task, context),向事件总线发布一个 DispatchEvent,其中记录 parent_session_id 指向父会话
  2. 执行:AgentWorker 订阅了 DispatchEvent,收到事件后为子智能体创建全新会话,异步执行任务
  3. 等待:派发方订阅 DispatchResultEvent,用一个临时的 asyncio.Future 挂起等待,并按 session_id 过滤,避免多个派发互相串线
  4. 清理:收到结果(或出错)后,在 finally 中取消订阅,返回 {"result": ..., "session_id": ...} 给主智能体

整个等待过程对 LLM 是"同步"的:从主智能体视角看,这就是一次普通的工具调用,只不过返回值来自另一个智能体的独立会话。

关键源码走读(3 个文件读懂派发机制)

文件 职责
subagent_tool.py 派发工具工厂:动态 schema + 发布事件 + Future 等待
agent_worker.py 订阅 DispatchEvent,为子智能体开会话并执行,完成后发回 DispatchResultEvent
events.py 事件类型定义:InboundEvent / OutboundEvent / DispatchEvent / DispatchResultEvent

几个值得留意的实现细节:

  • 会话隔离:子智能体的会话是全新的(agent.new_session),拥有自己的 session_id,上下文互不污染
  • 上下文传递:context 参数会拼接到任务后面一起下发,让子智能体拿到必要的背景信息
  • 结果即事件:AgentWorker 检测到事件类型是 DispatchEvent 时,回发的是 DispatchResultEvent 而非 OutboundEvent,把"回给用户"和"回给父智能体"两条链路彻底分开
  • 失败也有出口:执行异常时以 error 字段随 DispatchResultEvent 返回,父智能体能拿到错误信息而不是永远挂起

一键运行体验多Agent协作

准备工作与前面步骤一致,复制配置并填入 API 密钥即可:

cp default_workspace/config.example.yaml default_workspace/config.user.yaml

然后进入步骤 15 目录启动:

cd 15-agent-dispatch
uv run my-bot chat

试着对 Pickle 说一句 "Ask Cookie to read our README",它会自行调用 subagent_dispatch 把任务派给 Cookie,再把结果汇报回来。各步骤说明文档见 15-agent-dispatch/README.zh.md,智能体加载逻辑可参考 agent_loader.py。

直接派发之外:其他多智能体协作模式

subagent_dispatch 只是多Agent协作的一种形态。教程还提到了另外两种思路,适合不同场景:

  • 共享任务队列:多个智能体从同一队列领取任务,彼此不直接对话,松耦合更强
  • Tmux 技能:给智能体一个终端多路复用技能,让它自己开多个窗口并行干活

可以把它理解为协作光谱:直接派发(强上下文传递)→ 任务队列(完全解耦)→ 单智能体自管理多窗口(零协作成本)。

总结:把"分活"变成一次普通工具调用

build-your-own-openclaw 的步骤 15 用不到 150 行代码回答了多Agent协作的关键问题:

  • ✅ 谁可以派活:动态扫描 AGENT.md,schema 自动更新
  • ✅ 怎么派:DispatchEvent 上事件总线,父/子会话天然隔离
  • ✅ 怎么拿结果:DispatchResultEvent + Future,按 session_id 精准匹配
  • ✅ 失败怎么办:错误随结果事件回传,订阅器必定清理

理解这套机制后,你会发现"智能体团队"并不神秘——本质就是把跨智能体通信收敛成一次普通的工具调用。想继续深入,下一步可以看步骤 16 的并发控制:当多个智能体同时跑任务时,如何用速率限制和队列管理保住系统稳定。

登录后查看全文
build-your-own-openclaw