目标读者:AI Agent 开发者、Agent 框架设计者、需要评估"要不要上多智能体、上了之后怎么管"的工程负责人。
预备知识:知道大模型应用的基本形态(prompt + 工具调用循环);了解"会话/上下文"的概念。
代码来源: github.com/openai/code… · Rust 工作区 codex-rs · commit 8c07694(2026-10-18 克隆)
分析范围:本文只分析 V2 实现(工具命名空间 collaboration)。仓库中另有 V1 实现;V1 与普通 ReAct 执行模式的对比已单独成文《Codex 多智能体机制·执行模式对比》,本文不再展开。
篇目结构:全文分上下两篇。上篇(本篇,第 0–6 章)讲机制与架构——它是什么、由哪些部分组成、一次派生与一次通信如何完成;下篇(第 7–14 章,另见《Codex 多智能体机制分析_下篇_治理与实践》)讲治理与实践——资源如何被管住、如何配置、两个完整例子与借鉴清单。两篇章节编号接续,文中交叉引用均带“上篇/下篇”标注。
0. 先给结论
Codex 的多智能体不是一个"调度器",而是一套"让主 Agent 能把任务派给同构的子 Agent,并保证它们能安全地互相说话"的系统级基础设施。
它实现了四件和别的智能体框架实现机制不同的事:
- 没有中心编排器。谁该拆分任务、派给谁、何时等待,都由主 Agent 在 prompt 层决定;程序的运行时只负责"创建线程、隔离权限、投递消息、记账、回收"。这是纯粹的「模型决策 + 程序执行」分工。
- 子 Agent 是完整的 Codex,不是受限工具。子 Agent 拥有和父级一样的工具集、一样的沙箱与执行策略,甚至能自己再派生子 Agent(嵌套不设深度上限,由并发容量间接约束)。
- 用文件系统隐喻做寻址。每个 Agent 有一个这种格式的规范路径
/root/task1/task_3,Agent 间通信靠路径解析,而不是机器生成的 UUID。这让"谁是父级、谁是同层 Agent、能否通信"变成一次字符串运算。 - 默认极其克制。只有推理强度拉到
Ultra,Codex 客户端才会自动切换到 Proactive(主动式)多智能体模式,允许模型自主决定是否 spawn(创建)子 Agent 来并行处理任务;其他强度档位都只会在用户明确要求时才使用子 Agent。模式指令则明确限定:除非用户或 AGENTS.md/技能明确要求,否则不要派生。
一句话:Codex 把多智能体的复杂度从"编排逻辑"转移到了"运行时治理" ——编排交给模型,治理写成代码。
1. 使用场景:它解决什么问题
1.1 三类典型场景
先不讨论架构,先看三类真实场景。
场景一:一个任务里有几条互不依赖的支线。 用户说"帮我调研 Stripe、PayPal、PayID 三个支付平台的 webhook 签名验证机制,最后汇总成对比表"。串行做要查三遍文档,总耗时大约是顺序执行的三倍;并行做则是由三个子 Agent 各查一个平台,主 Agent 汇总。这正是 V2 Proactive 模式指令所鼓励的委派场景:只要委派能够节省时间或提升质量,就应当并行处理。
场景二:多个子 Agent 并行修改同一份代码。 多个子 Agent 同时修改同一文件时,后写入者会覆盖先写入者的修改,造成丢失更新。冲突避免依赖父 Agent 在派发阶段完成的任务拆分——将改动范围互不重叠的子任务分配给不同子 Agent;拆分由模型自行规划,运行时不做强制。换言之,并行修改代码的安全性取决于父 Agent 拆分任务的质量,而非运行时的保护。
场景三:上下文污染。 一次深度代码库分析会向上下文中载入数十个文件的内容,主 Agent 的上下文被这些中间细节挤占。将调研任务交由子 Agent 处理,子 Agent 处理完毕后仅返回一段结论,主 Agent 的上下文仅增加一段文字。子 Agent 的本质是把执行过程的上下文隔离在自己的线程里,父 Agent 只获得结论,从而避免上下文污染。
注意一个反直觉的点:主Agent不把关键路径上的阻塞任务指派给子 Agent。多智能体带来的是并行度,代价是等待——结果经消息通道异步回流,父 Agent 要么调 wait_agent 停等,要么把整合推迟到后续回合;而关键路径上的任务本就等不起,交给子 Agent 等于用等待换并行。这类任务应由父 Agent 自己完成。
1.3 多智能体机制的定义
Codex 的多智能体机制就是如下这三件事的工程实现:
- 派生:主 Agent 输出一个名为 spawn_agent 的工具调用请求,运行时由此工具创建一条完整的新对话线程,把任务消息作为初始输入。新线程有独立上下文,和主 Agent 的上下文互不干扰。
- 通信:父与子之间只传消息,不共享内存。消息分四种——派发任务时携带的初始任务、随时可发的队列留言、随时可发并唤醒目标的唤醒型消息、子 Agent 执行完毕后自动回流的结论。通信的目标不在内存里时,消息先进邮箱存着,不会丢失。
- 治理:一棵树同时最多几个 Agent 在运行、内存里同时驻留几个、整棵树共用多少 token 预算、出错了怎么不留"半棵树"——这些全是运行时要实现的管理机制,不靠模型支持。
后面所有章节,都是围绕这三件事来讲解。
2. 概念地图:关键名词对齐
Codex 的多智能体概念比一般框架多出两层,先集中说明。
| 概念 | 代码实体 | 说明 |
|---|---|---|
| 线程 Thread | CodexThread | 一条完整的对话,有独立的上下文、工具集、配置、持久化记录。线程 = Agent 的物理载体 |
| 会话 Session | Session | 线程内部的执行引擎:收 Op、调模型、执行工具、输出 Event |
| 线程管理器 | ThreadManager / ThreadManagerState | 所有线程的注册表与生命周期总管,Arc 包裹保证并发安全 |
| 智能体控制平面 | LocalAgentControl | 每个根会话一份,提供 spawn / send / wait / interrupt / list 这些动作 |
| 共享运行时 | LocalAgentRuntime | 一棵 Agent 树共享的状态:注册表、邮箱、驻留槽位、token 预算、关停跟踪 |
| Agent 路径 | AgentPath | 规范寻址路径,如 /root/task1/task_3。这是 Codex 最有辨识度的设计 |
| 角色 Role | agent_roles / AgentRoleConfig | 一组"只能收窄不能放大"的配置覆盖层(模型、推理强度、技能开关…) |
| 邮箱 Mailbox | Mailboxes | 目标 Agent 未加载时的暂存队列,保证消息不丢 |
| 驻留 Resident | V2Residency | 当前实际装载在内存中的子 Agent 槽位,空闲可被驱逐、按需重载 |
| Agent 图谱 | AgentGraphStore | 父子派生边的持久化(Open/Closed),用于重启后恢复树结构 |
2.1 路径即地址:/root/task1/task_3
这是理解 Codex 多智能体最直观的切入点。派生子 Agent 时,模型必须给一个 task_name,新 Agent 的规范路径 = 父路径 / task_name。于是:
- 主 Agent 是 /root
- 派三个调研子 Agent:/root/stripe、/root/paypal、/root/payid
- 其中 /root/stripe 再派一个查文档的:/root/stripe/docs
图 1:Agent 路径树与寻址规则。该图表达派生边如何长成一棵树、跨分支通信为何必须写全路径,以及一条路径如何同时编码身份、层级、可达性三件事。
命名与解析规则(全部由运行时强制,不靠模型自觉):
| 规则 | 内容 |
|---|---|
| 命名约束 | task_name 只允许小写字母、数字、下划线;非法名字在准备期就直接报错,不会走到建线程 |
| 拼接规则 | 子路径 = 父路径 join task_name,根路径固定为 /root |
| 绝对寻址 | 以 / 开头的引用全局解析,任何分支都能用全路径找到任何 Agent |
| 相对寻址 | 不以 / 开头的名字在调用者自己的分支下解析 |
| 子树过滤 | list_agents(path_prefix) 可按前缀列出某个子树下的活 Agent |
| 身份隐藏 | 默认 hide_spawn_agent_metadata = true:工具只返回 task_name,不把线程 UUID 暴露给模型 |
相对/绝对这条规则是通信边界的全部来源:工具说明书里专门举例——/root/task2/task_3 想联系 /root/task1/task_3,必须写全路径,因为相对名 task_3 在它自己的分支下会解析成另一个目标。由此形成"分支内可见、跨分支需显式全路径"的边界。
重启恢复时则反向使用该机制:从图谱存储列出所有 Open 的后代 → 并行读取它们的持久化元数据(限流 8 条并发)→ 按图顺序重新预约路径和昵称——顺序固定,恢复后的树和崩溃前一致。
为什么用路径而不是 ID? 因为模型是语言模型,不擅长记 UUID,但非常擅长处理"路径"这种结构化字符串。路径同时编码了三件事:身份、层级、可达性。一个字段同时解决寻址、拓扑与权限边界三个问题,编码效率很高。
2.2 关键枚举与状态速查
后面所有章节都会反复引用这几组枚举和状态,先集中摆出来。
版本与模式
| 枚举 | 取值 | 含义 |
|---|---|---|
| MultiAgentVersion | V1 / V2 / Disabled | 多智能体实现版本或整个关闭;本文只分析 V2 |
| MultiAgentMode | ExplicitRequestOnly / Proactive / Custom(文本) | 是否允许模型主动拆分任务。只有推理强度 = Ultra 才给 Proactive;Custom 允许宿主注入自己的行为准则 |
消息与寻址
| 枚举 | 取值 | 含义 |
|---|---|---|
| MessageDeliveryMode | QueueOnly / TriggerTurn | 只入邮箱不唤醒 / 入邮箱并唤醒对方开新回合 |
| AgentTarget | Id(ThreadId) / Reference(路径) | 按机器 ID 寻址 / 按规范路径寻址 |
Agent 终态 → 完成消息内容
| 子 Agent 状态 | 父 Agent 收到什么 |
|---|---|
| Completed(Some(msg)) | 原样 payload |
| Completed(None) | 空 payload(只有消息外壳) |
| Errored(err) | Agent errored: ... + 下一步建议 |
| Shutdown | Agent shut down. |
| NotFound | Agent was not found. |
| Interrupted | 不发消息(中断不算结果) |
| Running / PendingInit | 不发消息(还没到终态) |
其他
| 枚举 | 取值 | 含义 |
|---|---|---|
| ThreadSpawnEdgeStatus | Open / Closed | 派生边在图谱存储里的两种状态,重启恢复只认 Open |
| 驱逐结果 | 成功 / Busy / NotCurrent | Busy = 拿不到驻留写闸(有任务在执行);NotCurrent = 线程已被替换,不是当前注册的那个 |
| SessionSource::SubAgent | ThreadSpawn { parent, depth, agent_path, nickname, role } | 子会话的"出身证明":谁派的、第几层、路径、昵称、角色 |
3. 设计理念:七条主张与它们的代码证据
这一节是全篇的核心。每条主张给出「主张 → 证据 → 设计动机」。
3.1 主张一:编排是模型的活,不是框架的活
框架中没有 Plan、Router、Supervisor、Graph 这类编排对象,只有 6 个工具函数,以及分处多层的模型侧指令:工具说明书、角色提示、按推理强度切换的模式指令。
这些指令里信息量最大的几句:
- Explicit 模式(默认档):除非用户或 AGENTS.md或Skills技能明确要求子 Agent、委派或并行工作,否则不要派生;
- Proactive 模式(Ultra 档):只要通过委派并行化能够节省时间或提升质量,就应当派生;
- 模型覆盖:仅当用户或 AGENTS.md或Skiils技能明确要求时才设置 model 或 reasoning_effort;
- 等待策略:调用 wait_agent 时优先使用分钟级长等待,避免繁忙轮询;
- 并发约束:同时活跃的 Agent 数量(含根 Agent)不超过可用并发槽位数。
动机:编排策略需要随模型能力演进不断调整,写成代码则每次都要发版;写成 prompt 可以随模型一起灰度。而且模型能看到任务全貌,框架只能看到工具调用——让掌握全局信息的一方做决策,更具合理性。
代价:可验证性差、行为不稳定、不同模型表现差异大。Codex 用两层兜底压这个风险:多智能体模式开关(见 3.2)和运行时硬限制(见下篇第 7 章)。
3.2 主张二:默认不允许主动拆分任务,需达到模型能力门槛
判断逻辑只有一句:推理强度开到 Ultra → Proactive(可主动拆分);否则 → ExplicitRequestOnly(只在用户明确要求时派发任务)。
注意这个判据:只有推理强度开到 Ultra 才给 Proactive。这是一个相当务实的产品决策——拆分任务本身是个高难度判断(要识别并行性、评估子任务边界、预判等待成本),弱模型拆分出的子任务往往是错的,错误还会沿树形结构放大(子 Agent 继续派生子 Agent)。用"模型档位"当准入闸门,比用 prompt 劝说有效得多。
3.3 主张三:子 Agent 是「同构副本」,不是「受限工具」
工具说明书原话: "The spawned agent will have the same tools as you and the ability to spawn its own subagents."
代码层面也印证:子线程从父级复制配置、环境快照、插件选择、执行策略——未显式指定的都跟随父级。
动机:如果子 Agent 是"受限工具"(例如只能读取文件),就无法完成"修改代码"这类任务。同构意味着能力面等价,只是权限面可收窄(见 3.5)。
代价:递归失控。V2 不设深度上限,而是通过"并发驻留数"与"执行容量"进行约束——如果采用深度限制则会导致 /root/a/b/c 这类合理的逐层分解任务不能执行。
3.4 主张四:通信有四种物理形态,全部是异步的
| 形态 | 触发方式 | 是否需要目标存活 | 语义 |
|---|---|---|---|
| 派生时携带的初始 message | spawn_agent 的 message 字段 | 是(派生即启动) | "这是你的任务" |
| 队列消息 | send_message | 否(进邮箱) | "补充信息,暂不触发回合" |
| 唤醒型消息 | followup_task | 否(进邮箱并触发回合) | "新任务,立即触发回合" |
| 结果回流 | 子 Agent 回合终态时自动投递 | 是(终态事件) | "任务完成 / 任务失败" |
四种形态中,队列消息与唤醒型消息在实现上共用同一个投递函数,仅由 MessageDeliveryMode 枚举值区分(QueueOnly 与 TriggerTurn);结果回流由运行时在子 Agent 回合到达终态时自动触发,不经过工具调用。此外,wait_agent 提供同步等待语义,但它只读取既有状态,不产生新的消息形态。
没有共享内存、没有黑板、没有全局状态(AgentMessageBoard 是可选扩展,不是主路径)。父与子之间唯一的耦合是消息。这让每个线程可以独立加载、独立驱逐、独立恢复——第 7 节的"懒驻留"能力就是这条设计换来的。
3.5 主张五:权限只能收窄,不能放大
角色(role)的实现是"配置层叠加"(overlay),而且专门做了只能关不能开的过滤:
| 可覆盖项 | 方向 |
|---|---|
| developer_instructions / model / model_reasoning_effort / model_reasoning_summary / model_verbosity / personality / service_tier | 可改 |
| features(shell 工具、apps、插件、记忆工具、权限申请工具…) | 只允许写 false |
| skills | 只保留 disabled 项,上下文预算直接置空 |
动机:多智能体的安全边界不在"派了几个",而在"派出去的那个能干什么"。如果角色可以提权,一个被 prompt injection 影响的子 Agent 就能给自己开一个更宽的沙箱。这条约束让"派发任务"在权限上是单调不增的,整棵树的最大权限恒等于根会话。
3.6 主张六:拓扑要能重建,但不能成为瓶颈
父子派生边被持久化到独立的存储(AgentGraphStore),边状态只有 Open / Closed。临时会话(ephemeral)不记边。
Codex 选了双轨:
- 热路径:内存里的注册表(路径 → 线程 ID 的 HashMap),每次通信都走它,不碰磁盘;
- 冷路径:SQLite 里的图谱,只在重启恢复、谱系查询、审计时用。
动机:Agent 树不能仅存于内存,否则重启后树结构即丢失;但也不能让图数据库成为每次通信的必经之路,否则通信延迟将不可接受。热路径不碰磁盘,冷路径不参与调度。
3.7 主张七:失败必须原子,留给用户的不能是"半棵树"
派生是个多步操作:占槽位 → 建线程 → 注册路径 → 写图谱边 → 投递初始任务。中间任何一步失败,都不能留下一个已创建却无人管理的子 Agent。
Codex 用一个 RAII 守护对象解决(RAII 即“资源获取即初始化”:对象离开作用域时,析构逻辑自动执行,调用方无需显式清理)。派生过程中如果尚未"disarm"(解除守护),就在析构时自动执行清理——停止线程、丢弃持久化记录、将图谱边标记为 Closed。
这里最严谨的一个顺序约束:先写 Open 的异步任务必须先执行完成,清理才能写 Closed。否则后到的 Open 会覆盖清理写入的 Closed,重启后会残留一条指向已删除线程的边。这类顺序依赖是分布式系统中的典型陷阱,Codex 通过显式 join 处理。
4. 总体架构
4.1 分层视图
图 2:Codex 多智能体分层架构。该图表达「模型只决策、运行时只执行」的五层边界,以及工具调用请求、子 Agent 事件与持久化数据在层间的流向。
五个层次的职责边界非常清晰:
- 决策层只产出结构化的工具调用请求(调哪个工具、参数是什么),它不执行任何操作;
- 工具面是薄适配器:解析参数、做校验、转成内部请求、上报埋点;
- 控制平面是核心中枢:容量检查、槽位预约、路径生成、角色叠加、历史 fork、消息路由、结果回流;
- 线程运行时只关心"一条对话如何完成一个回合",完全不知道自己是根还是子;
- 持久化与观测横贯下层:ThreadStore 管历史与 rollout、AgentGraphStore 管父子派生边、rollout-trace 管树形 trace,另有可选频道的 AgentMessageBoard——它们只在冷路径参与,不在热路径上。
一个值得记住的分工陈述:大模型没有"派生子智能体"这个能力,它只输出了一个名为 spawn_agent 的函数调用请求;真正创建线程、复制历史、注册路径、写图谱边的是程序运行时实现。
按模块划分,各部分的职责如下(其中树级共享运行时、持久化、可观测未在分层图中单列,但在实现中与前四层并列):
| 模块 | 职责 |
|---|---|
| 决策面(模型回合) | 产出结构化工具调用请求,不做任何执行 |
| 工具面 | 参数解析、校验、转内部请求、埋点 |
| 控制平面 | 容量检查、槽位预约、路径生成、角色叠加、历史 fork、消息路由、结果回流 |
| 树级共享运行时 | 注册表、邮箱、驻留槽、预算、关停跟踪 |
| 线程运行时 | 一条对话的 Op → Event 提交循环,不感知自己是否为子 |
| 持久化 | 对话历史、派生边、可选消息板 |
| 可观测 | 线程 rollout、树形 trace、事件通知、埋点 |
模块间协作的主流向:模型回合产出工具调用请求 → 工具面校验转译 → 控制平面做准入与调度 → 线程运行时执行 → 终态事件经控制平面渲染成消息回流到父回合。持久化只在冷路径参与,不在热路径上。
4.2 为什么控制平面是"每会话一份"而不是"全局一份"
LocalAgentControl 持有的是线程管理器的弱引用——根会话结束时,控制平面自动失效。
这是一条强约束:不存在跨会话的 Agent 树。好处是资源归属清晰(每棵树由其根会话负责回收)、安全边界清晰(会话是权限单位)、清理逻辑简单(随根会话一并终止)。坏处是没有"跨会话常驻的专家 Agent"——如果你要那种能力,得靠 AgentMessageBoard 或外部服务。
4.3 线程对象的内部结构
图 3:单条线程的内部结构。该图表达 CodexThread 如何组合驻留读写闸、持久化句柄、树级共享运行时克隆与执行引擎,以及"注册表是同一个对象"带来的跨分支可见性。
关键点:每个子线程都持有一份树级共享运行时的克隆,但注册表是同一个对象。所以 list_agents 能从任意子 Agent 里看到整棵树;而恢复时校验"这个子线程确实属于我这个父线程",靠的是注册表内存地址相等(Arc::ptr_eq)——用指针身份作为"树身份",比生成 UUID 再逐层比对成本低得多。
4.4 Op/Event 的多智能体扩展:提交循环如何长出协作变体
4.1 说过,线程运行时只关心“一条对话如何完成一个回合”。多智能体并没有另造一套执行模型,而是在同一套 Op 进、Event 出的提交循环上做了三处扩展。
| 扩展维度 | 机制 | 说明 |
|---|---|---|
| 工具登记 | 协作工具在协议层统一登记为 CollabAgentTool 枚举 | V2 工具面暴露 6 个工具,枚举中另有 4 个 V1 遗留值。每次协作调用都会生成一条工具调用记录(调用方、接收方、提示词、模型、推理强度、状态),既是埋点,也是 UI 事件的原料 |
| 消息投递 | 投递被封装为 InterAgentCommunication Op | “给另一个 Agent 发消息”与“用户输入”走同一条提交入口,只是载荷不同——投递在运行时眼中与普通输入同构,无需为 Agent 间通信单开通道 |
| 可观测事件 | EventMsg 长出 Collab 系列事件 | 派生开始/结束、交互开始/结束、恢复开始/结束、等待开始/结束、关闭开始/结束,驱动 UI 展示“哪个 Agent 正在派生、被交互、在等待” |
其中一个细节值得注意:V2 刻意让四个消息类工具(send_message、followup_task、interrupt_agent、list_agents)不产生 UI 事件,只记录埋点。消息投递被设计为对界面安静的操作——用户看得到的是派生、交互、恢复、等待、关闭五类“重事件”。这与 6.5 的端到端链路互为印证:普通消息进邮箱或输入队列即可,本就不需要惊动用户。
这三处扩展全部在线程运行时内消化,控制平面只负责把投递请求转译成对应的 Op——分工与 4.1 的分层视图一致:模型决定调哪个工具,运行时决定这个调用在提交循环里长成什么样。
5. 生命周期:一次 spawn_agent 的完整过程
5.1 时序图
图 4:一次 spawn_agent 的完整时序。该图表达从模型输出工具调用请求、经控制平面完成准入与调度、到子 Agent 终态以 FINAL_ANSWER 消息回流父回合的 17 步全过程;其中步骤 3–13 为工具面转译与运行时自治环节(模型不参与),在 5.2 中按关注点归并为十一个关键步骤;紫色为驻留槽满员时的 LRU 驱逐旁路,红色为任一步失败时的 RAII 回滚。
5.2 运行时自治环节:十一个关键步骤
图 4 中步骤 3–13 覆盖工具面转译与运行时自治环节,下表按关注点将其归并为十一个关键步骤。
| # | 动作 | 关键细节 |
|---|---|---|
| 1 | 解析工具参数 | message / task_name 必填;fork_turns 只接受 none/all;拒绝旧字段 |
| 2 | 生成子配置 | 角色叠加、模型/推理强度覆盖、是否全量 fork |
| 3 | 路径拼接 | 父路径 join task_name,非法名字直接返回准备期错误 |
| 4 | 构造会话来源 | 记下父线程、深度、路径、昵称、角色 |
| 5 | 树准入 | 树正在关停时,拒绝新成员 |
| 6 | 执行容量检查 | 仅子 Agent 派生时受限;根 Agent 不受限 |
| 7 | 驻留槽位预约 | 满了就驱逐最久未用的空闲子 Agent |
| 8 | 继承上下文 | 环境快照、插件选择、执行策略(按策略允许时) |
| 9 | 历史 fork | 全量 fork 时过滤历史项(见 5.3) |
| 10 | 建线程 | 创建 Session、注册到线程表、写 rollout |
| 11 | 收尾与兜底 | 写图谱边(Open)+ 启动完成监听;失败则 RAII 自动回滚 |
5.3 一个容易被忽略的细节:fork 历史是「有损」的
子 Agent 获得的并非父级完整上下文,而是经过筛选的:
| 处理 | 历史内容 |
|---|---|
| 保留 | 用户消息、system/developer 消息、assistant 的阶段性回答与最终答案、工具清单、无 call_id 的工具输出、配置变更记录 |
| 丢弃 | 推理过程、本地 shell 调用、函数调用、搜索、图像生成、各种压缩标记、agent 间通信记录、token 用量记录 |
保留"用户提出了什么、最终结论是什么",舍弃"模型如何推理、调用了哪些工具"。这既节省 token,也避免子 Agent 受到父级中间推理过程的干扰——子 Agent 需要的是任务与背景,而非父级的中间推理细节。
配套还有一条:子 Agent 继承的是模型上下文,不是父级的累计用量状态,预算记账是共享的(见下篇 7.4)。
6. 通信机制:消息的投递路径
6.1 四条路径与两级暂存结构
图 5:Agent 间通信机制。该图表达初始任务、邮箱入队、唤醒型消息与终态回流各自的路径,以及"已装载进输入队列、未装载进邮箱"的两级结构。
这里有一个巧妙的设计:邮箱与输入队列构成两级结构。
- 目标 Agent 已装载(驻留中) :消息直接进入其输入队列,参与正常回合调度(保持顺序性);
- 目标 Agent 未装载(已换出) :消息进入邮箱(内存中的 per-thread 队列),只存不唤醒;待其下次被装载时一次性取出。
6.2 send_message 与 followup_task 的差异(常见混淆点)
| 维度 | send_message | followup_task |
|---|---|---|
| 投递模式 | QueueOnly | TriggerTurn |
| 空闲目标 | 不会被唤醒,消息暂存于邮箱 | 立即开一个新回合 |
| 运行中目标 | 在消息边界或工具完成后送达 | 同左,但不改变已有回合 |
| 能否发给根 | 可以 | 不可以(只能发给非根目标) |
| 典型用途 | 补充约束、纠偏 | 派新任务、要求继续 |
注意容量检查的位置:只在要唤醒时才检查执行容量。纯入队不占容量,父 Agent 可以向一个休眠子 Agent 的邮箱写入多条消息而不触发限流。
6.3 结果流回的原文格式
子 Agent 终态时,父 Agent 的上下文里会出现这样一段:
Message Type: FINAL_ANSWER
Task name: /root/stripe
Sender: /root/stripe
Payload:
<子 Agent 的最后一条消息>
三个细节值得注意:
- Message Type: FINAL_ANSWER —— 复用了模型训练中熟悉的"最终答案"标记,模型看到就知道这是"结论"而非"指令";
- role = "assistant" —— 子 Agent 的结论被渲染成父 Agent 自己说出来的话。语义上很微妙:它不是"别人告诉我",而是"我想到了"。好处是父 Agent 更容易把它当自己的认知继续推进;坏处是削弱了信任边界(见下篇第 13 章);
- 带 Task name 和 Sender —— 保留溯源能力,父 Agent 知道这段话来自哪个分支。
终态映射见 2.2 的表格:Interrupted 和未达终态的状态不产生消息。
6.4 wait_agent 等的是"事件",不是"结果"
wait_agent 的工具描述写得很明确:不返回内容,只返回"哪些 Agent 有更新"的摘要。
它的实现是订阅输入队列的活动信号——任何已装载 Agent 的邮箱有更新、到达终态,或被用户 steer 打断,都会提前返回。
设计意图是:让子 Agent 在后台执行,父 Agent 继续处理自身任务,依靠结果消息异步回流,而非阻塞等待。 wait_agent 是兜底机制,不是主路径。
6.5 端到端:一条消息的完整旅程
把前面的机制串起来看:一次 send_message 从模型输出到进入目标 Agent 的输入队列,要走过四段路程。
图 6:一次 Agent 间消息的端到端投递链路。该图表达从模型输出工具调用请求,经工具面共用入口与控制平面的目标解析、驻留判定,到三个终点分支(输入队列直投、树级邮箱暂存、按需重载并触发回合)的完整路径。
- 模型输出工具调用请求。send_message 与 followup_task 在模型眼中是两个工具,参数都是目标(路径或昵称)与消息内容;选用哪个工具,直接决定消息的投递模式(QueueOnly 或 TriggerTurn)。
- 工具面共用入口。两个工具在实现上走同一个处理函数:解析目标与消息、确定投递模式、构造内部投递请求。工具面不关心目标是否存活,只做参数校验与转译。
- 控制平面做两件事:先把目标路径解析成线程 ID(注册表查询),再根据目标当前是否已装载,决定消息的去处。
- 三个终点分支。目标已装载且为普通消息,直接进入输入队列,参与回合调度或在消息边界送达;目标未装载且为普通消息,进入树级邮箱暂存,不触发任何动作;唤醒型消息(followup_task)无论目标是否装载,都会先确保其装载(校验父线程所有权、恢复历史、搬回积压邮件),再开一个新回合。
这条链路解释了前面几节的诸多设计:邮箱“只存不唤醒”,是因为普通消息(QueueOnly)本就不以唤醒为目标;Agent换出时必须搬走邮箱,是因为未装载目标的消息最终都汇入树级邮箱;wait_agent 等的是“事件”而非“结果”,因为它订阅终态信号,并不参与本链路的消息投递。
总结
至此,机制层面的拼图已经完整:一次 spawn_agent 的完整流程(第 5 章)、消息的投递路径(第 6 章),以及背后「模型决策、程序执行」的分工(第 4 章)。
下一篇讲解工程层面的实现:
- 一棵树同时能跑几个 Agent?内存里驻留几个?谁被换出、何时重载?
- 角色如何收窄权限、模型如何按成本分层?
- Guardian 这类评审型 Agent 与协作 Agent 有何不同?
- 一棵树如何被记录与观测,以及两个完整例子与借鉴清单。