Multi-Agent

Codex 的 multi-agent 不是简单开多个模型请求。它把每个子 agent 表示为一个独立 thread，并用 AgentControl 维护 root thread 范围内的 agent registry、spawn 限额、residency、inter-agent communication 和 fork 语义。

Multi-Agent

AgentControl

codex-rs/core/src/agent/control.rs 说明：AgentControl 在一个 root session tree 内共享。它持有：

  • session_id：root 与所有 sub-agent 共享。
  • Weak<ThreadManagerState>：避免引用环。
  • AgentRegistry：记录 agent metadata、状态和 parent/child 关系。
  • V2Residency：multi-agent v2 的 resident thread 管理。
  • AgentExecutionLimiter：spawn/执行容量限制。
  • RolloutBudget：agent 树共享 rollout budget。

Spawn Agent

spawn 逻辑在 codex-rs/core/src/agent/control/spawn.rs：

  1. 根据 config 和 session source 解析 multi-agent version。
  2. 检查执行容量和 spawn 深度。
  3. 如果是 v2 resident source，预留 residency slot。
  4. 预留 agent registry slot。
  5. 继承 parent environments、exec policy、multi-agent mode。
  6. 根据 fork_mode 决定新线程或 forked thread。
  7. 注册 metadata，通知 parent，并提交初始操作。

Fork Mode

SpawnAgentForkMode 支持：

  • FullHistory
  • LastNTurns(usize)

fork 时不会盲目复制所有 rollout item。keep_forked_rollout_item 会保留 system/developer/user message、final assistant answer、必要的 TurnContext、compacted/event/session metadata；丢弃 reasoning、tool call、tool output 等不适合直接放入子线程的中间项。

V2 Residency

codex-rs/core/src/agent/control/residency.rs 实现 LRU resident thread 管理：

  • reserve_slot 会先尝试预留 pending slot。
  • 容量满时扫描 resident candidates。
  • 只卸载 completed、errored、interrupted 且没有 active turn、没有 pending mailbox 的线程。
  • 卸载前确保 rollout materialized，再 shutdown 并从 live thread map 移除。
  • protected thread 不会被本次卸载选中。

这让 v2 sub-agent 可以按需恢复，同时控制 live thread 数量。

Inter-Agent Communication

父子 agent 之间使用 InterAgentCommunication 作为 protocol item。它可以作为 fork turn boundary，也会更新 agent 的 last task message。这样 UI 可以展示每个 agent 当前任务，而不是只知道它“正在跑”。

工具暴露

multi-agent 工具分 v1/v2：

  • v1：spawn、send input、wait、close、resume 等。
  • v2：list agents、spawn、send message、wait、interrupt、followup task 等。

这些工具仍然通过 ToolRouter -> ToolRegistry -> ToolCallRuntime 进入统一工具 harness。

可学习的设计

Multi-agent 的关键不是并发本身，而是 residency 和历史继承：

  • 每个 agent 是 thread，天然复用持久化、压缩、权限和工具系统。
  • fork 时按 turn boundary 和 item 类型清洗历史。
  • v2 用 LRU resident 管理控制资源。
  • inter-agent communication 是协议对象，而不是普通字符串。