多Agent协作与通信的MessageBus最小实现

如果你已经体验过“单 Agent + 工具循环”的编程模式，大概率会遇到一个相当尴尬的场景：模型去扫描一遍代码仓库、读取大量测试用例，结果主对话直接被工具输出的信息塞满；你想让它一边规划，一边派人手去查阅文档，却只能串行等待 subagent 跑完；后台任务明明完成了，还得你手动把结果粘贴回主对话里——这种效率显然说不过去。

Agent Teams 的思路非常直白：一个 Lead 负责统筹调度，Teammate 在独立线程里运行自己的循环，彼此之间通过一个 MessageBus 互相传递消息；Lead 则通过 inbox 注入，把队友的结果接回自己的主上下文。一句话总结：谁干活，谁负责沟通，各行其道，互不干扰。

下面通过一个对比来清晰理解优势。

一、与同步 Subagent 相比有何不同？

许多教学示例中，subagent 都是这样运行的：Lead 调用 task 工具 → 等待 subagent 跑完（这里会阻塞） → 整段历史作为 tool_result 塞回 Lead。处理简单任务还行，一旦任务复杂化，你就能体会到那种“等得心焦”的感受——Lead 无法一边思考下一步，一边让队友去查资料。

Agent Teams 则换了思路：Lead 调用 spawn_teammate 时，不会傻等。后台线程直接启动 teammate_loop（不阻塞），Lead 可以继续对话或处理其他事务。Teammate 完成后通过 BUS.send 把结果扔进 Lead 的 inbox，后台的 queue_processor 发现 inbox 里有消息后，自动唤醒 Lead 的 agent_loop。Teammate 不再是工具返回的临时变量，而是一个在后台真正运行起来的工人角色。

二、三张图看懂整体架构

1. 三条事件流，共用同一个 Lead

① 用户打字 → history → agent_loop
② Cron 到点 → _queue → inject → agent_loop
③ Teammate 回信 → inbox → inject → agent_loop

Cron 和 Teammate 都不会直接调用模型“乱入”，而是被打包成外部事件，由后台的 queue_processor 抢锁后统一交给 Lead 的 agent_loop 消费。说实话，这种机制是许多成熟 Agent Runtime 的共同形态，算不上新鲜，但对教学理解非常有帮助。

2. Lead / MessageBus / Teammate 的关系

Lead agent loop MessageBus Teammate loop +----------------+ +-----------+ +-------------+ | prompt + tools | --spawn----->| .jsonl | <---send---- | own history | | inject inbox | <---send------ | 邮箱 | ---inbox---> | own tools | +----------------+ +-----------+ +-------------+

3. 关键设计：共享磁盘，隔离上下文

这里有两个要点值得关注：

• 共享工作目录：Lead 和 Teammate 都挂载同一个 bash 环境、读写相同的文件（教学版未做权限隔离，但思路清晰）。
• 隔离上下文：Lead 与 Teammate 不共享 messages 列表。队友读了哪些文件、执行了哪些命令，都保留在队友自己的上下文里；Lead 最终只看到 inbox 中那条 result。

换句话说，队友干完活，只给 Lead 提交一份最后的“报告”，不会把中间的一大堆调试信息也塞进去。

三、MessageBus：用文件充当邮箱（教学版）

生产环境下，MessageBus 通常对应 Redis、Kafka 或数据库队列表。但教学代码为了把机制讲清楚，直接采用每个 Agent 一个 JSONL 文件来模拟邮箱，效果毫不含糊。

目录结构是这样：

.mailboxes/ lead.jsonl reviewer.jsonl

send() 操作就是向目标文件 append 一行 JSON：

{"from": "reviewer","to": "lead","content": "Parser looks good","type": "result","ts": 1779780000.0}

read_inbox() 则直接读取并删除文件——消费式操作，同一行消息不会重复注入。简单粗暴，但足够说明核心逻辑。

四、Lead 新增三个“团队工具”

spawn_teammate 的底层其实只是一个守护线程：

threading.Thread( target=teammate_loop, args=(client, model_name, name, role, prompt), daemon=True, ).start()

Lead 立刻获得“已启动”的信息，不会被卡在队友的十轮工具循环里。

五、Teammate 如何运行？刻意的限制

Teammate 拥有自己的 system prompt 和 messages，入口任务来自 Lead 的 prompt。教学版中工具白名单定义如下：

• 可用：bash、read_file、write_file、edit_file、send_message
• 不可用：spawn_teammate、schedule_cron……（避免队友再 spawn 队友，防止复杂度失控）

轮数上限锁定为 10 轮工具循环，防止后台线程无限消耗 token。任务结束——无论成败——都会通过 BUS.send 把结果发回 Lead，然后从 active_teammates 中注销。相当于一个人在后台默默干完活，递上报告就下线了。

六、Inbox Injection：为什么伪装成 user 消息？

Lead 每轮调模型前会执行 inject_inbox_messages(messages)，即读取 lead.jsonl → 删除文件 → 追加一条 user 消息。注入的内容大致像这样：

[reviewer:result] queue_processor 会监听外部事件并安全唤醒 Lead……

你可能会问：为什么一定要是 role: user？

其实很简单——对 Agent Loop 来说，inbox、cron 触发、用户打字都是“外部世界发来的新事件”。模型下一轮统一按“用户侧输入”处理，完全不需要为每种事件单独设计 role。Cron 触发也是同样的逻辑，只不过用 包了一层。

这种设计的好处是：系统统一、实现简单，并且后续扩展事件类型时无需修改核心 loop。

七、Queue Processor：cron 与 inbox 共用一个唤醒器

上一篇讲 cron 时，后台线程只盯着定时队列。这一版条件放宽了：判断 SCHEDULER 是否有任务待执行，或者 BUS 的 lead 邮箱里是否有新消息。如果两者都没有，就继续休眠；如果有一个有，就尝试非阻塞获取 agent_lock，拿到锁就跑一轮 agent_loop(history)。

agent_lock 解决了一个很现实的问题：用户正在终端输入时，后台不能同时修改同一份 history。拿不到锁就 0.2 秒后再试一次，避免数据冲突。

八、和定时任务如何整合在一起？

这里没有替换掉 cron，而是直接将两者并入同一套“外部事件”模型中：

cron 到点 → tick 入队 → inject_cron_jobs → 队友完成 → send 到 lead → inject_inbox_messages → ↓ queue_processor → agent_loop → 模型 + 工具

持久化方面，cron 的 durable=True 会将任务写入 .scheduled_tasks.json，重启后 load() 恢复；已到点但未消费的队列仍在内存中，进程挂了就没了——这是教学版本的边界。

九、本地如何运行？一条命令试全队

环境变量很简单，就是一个 .env 文件：

OPENAI_BASE_URL OPENAI_API_KEY MODEL_NAME

在仓库根目录执行：

python3 harness_agent/09_agent_teams.py

推荐你直接复制这一句到终端试试：

启动一个 teammate，名字叫 reviewer，角色是 code reviewer。让它阅读 harness_agent/09_agent_teams.py，用几句话说明 MessageBus 怎么工作。

预期效果如下：

1. Lead 调用 spawn_teammate，终端打印 [teammate] reviewer spawned；
2. 你可以继续输入其他指令，或者等待；
3. reviewer 完成后终端出现 [bus] reviewer -> lead，[queue processor] delivering external work；
4. Lead 被自动唤醒，根据 inbox 内容回复你。

全程无需你手动粘贴结果，prompt 写个任务，剩下的交给系统自动流转。

十、教学版刻意没做啥（读代码时需了解）

清楚这些边界，你才明白下一版该往哪个方向扩展。

十一、带走三句话

1. 多 Agent 不等于多个模型随意调用——必须有消息边界（MessageBus）和主 loop 串行消费（queue processor + lock）。
2. 协作靠异步，隔离靠独立 messages——Lead 不会被队友的工具轨迹淹没。
3. Cron、用户输入、队友回信——形态不同，本质都是“外部事件注入主 loop”。

从一个人干活到一个小队分工，这是 Coding Agent 走向工程化协作的第一步。往后还能叠加权限管理、结构化 schema、队友生命周期管理——但邮箱 + 注入 + 后台唤醒这条骨架，已经足够你跑通第一版了。