多Agent协作揭秘:build-your-own-openclaw子智能体派发subagent_dispatch完整实现
多Agent协作揭秘:build-your-own-openclaw子智能体派发subagent_dispatch完整实现
在 build-your-own-openclaw 这个 18 步渐进式教程中,多Agent协作 是"自主与多智能体"阶段的核心能力。本文带你完整读懂它的子智能体派发机制:主智能体 Pickle 如何把任务分派给其他专业智能体,subagent_dispatch 工具又是如何通过事件总线(EventBus)把"派发—执行—取回结果"串成闭环的。
为什么需要子智能体派发?
单个智能体什么都能干,但往往不够专业。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 的发布/订阅协作,完整流程如下:
- 发布:主智能体调用
subagent_dispatch(agent_id, task, context),向事件总线发布一个 DispatchEvent,其中记录parent_session_id指向父会话 - 执行:AgentWorker 订阅了
DispatchEvent,收到事件后为子智能体创建全新会话,异步执行任务 - 等待:派发方订阅 DispatchResultEvent,用一个临时的
asyncio.Future挂起等待,并按session_id过滤,避免多个派发互相串线 - 清理:收到结果(或出错)后,在
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 的并发控制:当多个智能体同时跑任务时,如何用速率限制和队列管理保住系统稳定。
