如果你已经体验过“单 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 | 根据 name / role / prompt 启动后台队友 |
| send_message | 给某个 agent 发送消息（队友之间也可互相传） |
| check_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 消息。注入的内容大致像这样：
你可能会问：为什么一定要是 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 →
持久化方面，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 怎么工作。
预期效果如下：
- Lead 调用 spawn_teammate，终端打印 [teammate] reviewer spawned；
- 你可以继续输入其他指令，或者等待；
- reviewer 完成后终端出现 [bus] reviewer -> lead，[queue processor] delivering external work；
- Lead 被自动唤醒，根据 inbox 内容回复你。
全程无需你手动粘贴结果，prompt 写个任务，剩下的交给系统自动流转。
十、教学版刻意没做啥（读代码时需了解）
| 简化点 | 真实系统常见补法 |
|---|---|
| 文件 JSONL 邮箱 | MQ / DB / gRPC |
| 单进程锁 | 分布式锁、ack、重试 |
| Teammate 最多 10 轮 | 长期 worker、idle 唤醒 |
| 共享工作目录 | 沙箱、per-agent 权限 |
| 无取消/超时/成本上限 | lifecycle、budget、审计 |
清楚这些边界，你才明白下一版该往哪个方向扩展。
十一、带走三句话
- 多 Agent 不等于多个模型随意调用——必须有消息边界（MessageBus）和主 loop 串行消费（queue processor + lock）。
- 协作靠异步，隔离靠独立 messages——Lead 不会被队友的工具轨迹淹没。
- Cron、用户输入、队友回信——形态不同，本质都是“外部事件注入主 loop”。
从一个人干活到一个小队分工，这是 Coding Agent 走向工程化协作的第一步。往后还能叠加权限管理、结构化 schema、队友生命周期管理——但邮箱 + 注入 + 后台唤醒这条骨架，已经足够你跑通第一版了。
