第14章：多 Agent 委派 —— 从子进程到协作图

第14章：多 Agent 委派 —— 从子进程到协作图

Pi 明确不做子 agent（"用 tmux"）。dsh 做了四种委派机制。Codex 做了两代，第二代把主 agent 的角色从"干活的"改成"协调的"——并且把这个转变直接写进了系统提示词。本章拆这个演进。

一、两代并存

pub enum MultiAgentVersion { Disabled, V1, V2 }

[源码 protocol/src/protocol.rs:2844]

三态，且版本被持久化在 rollout 的会话元数据里（第 12 章的 RolloutParams::Create.multi_agent_version）。恢复一个 V1 时代的会话，它还是按 V1 跑。

两代的工具集不一样 [源码 core/src/tools/handlers/]：

差异不大，但方向很清楚：

• V1 的动词是"控制"：spawn / send_input / close / resume —— 像在管理子进程
• V2 的动词是"协作"：send_message / followup_task / list_agents / interrupt —— 像在管理同事

message_tool.rs 的注释点出了 V2 的一个实现细节 [源码]：

Shared argument parsing and dispatch for the v2 agent messaging tools. send_message and followup_task share the same submission path and differ only in whether the …

（v2 agent 消息工具的共享参数解析与分发。send_message 和 followup_task 走同一条提交路径，只在……上有区别。）

"发个消息"和"派个后续任务"底层是同一件事，区别只在语义标记上。这个抽象是对的——对一个 agent 来说，收到消息和收到任务本来就没有本质区别。

二、主 agent 变成协调者

Codex 仓库里有一份 core/templates/agents/orchestrator.md（4972 字节）。它的最后一节直接规定了主 agent 的行为 [源码]：

General guidelines

• Prefer multiple sub-agents to parallelize your work. Time is a constraint so parallelism resolve the task faster.
• If sub-agents are running, wait for them before yielding, unless the user asks an explicit question.
  • If the user asks a question, answer it first, then continue coordinating sub-agents.
• When you ask sub-agent to do the work for you, your only role becomes to coordinate them. Do not perform the actual work while they are working.
• When you have plan with multiple step, process them in parallel by spawning one agent per step when this is possible.

（优先用多个子 agent 并行化你的工作……如果子 agent 在跑，在交还控制权前先等它们，除非用户提了明确问题……当你让子 agent 替你干活时，你唯一的角色就变成协调它们。不要在它们工作时自己动手。……有多步计划时，尽可能每步派一个 agent 并行处理。）

"Do not perform the actual work while they are working" 是本章最值得记的一句。

它解决的是多 agent 系统里一个非常具体的失败模式：主 agent 派完活之后闲不住，自己又去干了一遍。结果是重复劳动、文件冲突、上下文爆炸。用一句提示词把主 agent 的角色钉死，比任何架构约束都直接。

可迁移的判断 ㉕ 多 agent 系统里，"主 agent 派活之后该干什么"必须被显式规定，否则它会两边都做。

Codex 的规定是三条：只协调不干活、交还控制权前先等、用户提问优先回答再继续协调。这三条可以直接抄进任何 orchestrator 提示词。

对本仓的启示：本仓的 subagent 使用（Explore / general-purpose）目前是"派出去、等结果、自己接着做"。如果要做真正的并行编排，这三条约束是起点。

三、Agent 就是一个新的 Session

第 3 章讲过那条约束：一个 Session 同时只能跑一个 Task。所以并行的唯一办法是多个 Session。

AgentControl（862 行）+ AgentRegistry（406 行）就是管这个的。看 control.rs 的 import 列表就知道 spawn 一个 agent 涉及多少东西 [源码 core/src/agent/control.rs:1-56]：

use crate::thread_manager::ResumeThreadWithHistoryOptions;
use crate::thread_manager::ThreadIdGenerator;
use crate::thread_rollout_truncation::truncate_rollout_to_last_n_fork_turns;
use crate::rollout_budget::RolloutBudget;
use crate::agent::role::resolve_role_config;
use crate::agent_communication::AgentCommunicationContext;
use crate::session_prefix::format_inter_agent_completion_message;
use crate::session_prefix::format_subagent_context_line;
…

子 agent 拿到的是父会话历史的一个截断分叉（truncate_rollout_to_last_n_fork_turns），不是完整历史——第 12 章讲的分叉机制在这里被复用。

ThreadHistoryMode 的三种模式（Legacy / Paginated / …）和 subagent_history_start_ordinal 也是为这个服务的：子 agent 从父会话历史的哪一条开始看。

四、AgentRegistry：给自由度加上限

这个结构体的文档注释很直白 [源码 core/src/agent/registry.rs:18]：

This structure is used to add some limits on the multi-agent capabilities for Codex. In the current implementation, it limits:

• Total number of sub-agents (i.e. threads) per user session

This structure is shared by all agents in the same user session.

pub(crate) struct AgentRegistry {
    active_agents: Mutex<ActiveAgents>,
    total_count: AtomicUsize,
}

struct ActiveAgents {
    agent_tree: HashMap<String, AgentMetadata>,
    thread_paths: HashMap<ThreadId, RegisteredAgent>,
    used_agent_nicknames: HashSet<String>,
    nickname_reset_count: usize,
}

一个用户会话内的子 agent 总数有上限，且这个计数被所有 agent 共享。

为什么必须有？因为提示词里刚说了"尽可能每步派一个 agent"。没有上限的话，一个"重构整个项目"的任务能瞬间派出几十个 agent，每个都在跑模型、都在写文件。

注意 total_count 是 AtomicUsize 且只增不减——它记的是"这个会话总共派过多少个"，不是"现在有几个活的"。限制的是累计量，防止"关一个开一个"绕过限制。

昵称

used_agent_nicknames: HashSet<String> + nickname_reset_count + rand::prelude::IndexedRandom——子 agent 有随机分配的昵称，且不重复。

这纯粹是给人用的：UI 里显示 "agent-falcon 正在跑测试" 比 "thread-01H8X…" 好懂太多。用完一轮再复用（nickname_reset_count）。

AgentPath

agent_tree: HashMap<String, AgentMetadata> 里的 key 是路径字符串，配合 codex_protocol::AgentPath 类型。agent 是一棵树（子 agent 还能派孙 agent），路径编码了它在树里的位置。

五、角色：能收缩，不能扩张

agent/role.rs 的模块注释是本章第二个关键点 [源码 core/src/agent/role.rs:1]：

Applies bounded agent-role overrides to an existing session config.

Roles may customize the child or reduce its capabilities, but never replace the parent session's authority. A projected layer keeps existing layer-based consumers in sync.

（对已有会话配置施加有界的 agent 角色覆盖。角色可以定制子 agent 或削减它的能力，但绝不能替换父会话的权限。）

可覆盖的字段 [源码 core/src/agent/role.rs:37]：

struct AgentRoleOverrides {
    developer_instructions: Option<String>,
    model: Option<String>,
    model_reasoning_effort: Option<ReasoningEffort>,
    …  // personality / verbosity / service_tier / skills / features …
}

"只能收缩不能扩张"是多 agent 安全的核心不变量。

反例很好想：如果子 agent 的角色配置能把沙箱策略从 read-only 改成 danger-full-access，那攻击者只要能影响角色配置（比如通过一个仓库里的 .codex/agents/*.toml），就能用"派一个子 agent"绕过所有权限限制。

角色配置从文件读取时还用了 read_sensitive_file_to_string [源码 core/src/agent/role.rs:17]——角色文件被当作敏感文件读（走执行器抽象、受沙箱管辖）。

DEFAULT_ROLE_NAME = "default"，以及一个专门的错误文案 "agent type is currently not available"——角色可以被禁用。

可迁移的判断 ㉖ 委派机制的权限必须是单调收缩的：子任务的权限 ⊆ 父任务的权限，无例外。

这条听起来显然，但很容易被"配置覆盖"这类机制悄悄打破。判断方法：问自己"如果这份配置来自一个不可信的仓库，最坏会怎样"。

六、通信：不只是返回值

agent_communication.rs + InterAgentCommunication（第 12 章看到它是一种被持久化的 rollout 条目）+ AgentCommunicationKind。

几个相关的上下文片段（第 6 章那 44 个里的）：

六个片段专门服务多 agent。 这说明通信不是"子 agent 返回一个字符串"那么简单——父子之间要同步状态、要通知完成、要传递角色语义。

session_prefix.rs 里的两个格式化函数 [源码 core/src/agent/control.rs:20-21]：

use crate::session_prefix::format_inter_agent_completion_message;
use crate::session_prefix::format_subagent_context_line;

子 agent 的上下文里有一行前缀，说明"你是谁、你为谁工作"。

七、agent-graph-store：拓扑是独立存储

一个只有 479 行的小 crate，但它的文档注释说明了架构意图 [源码 agent-graph-store/src/lib.rs:1]：

Storage-neutral parent/child topology for thread-spawned agents.

pub use error::AgentGraphStoreError;
pub use local::LocalAgentGraphStore;
pub use store::AgentGraphStore;         // trait
pub use types::ThreadSpawnEdgeStatus;

父子拓扑被抽象成一个独立的、存储中立的 store，有 trait 和本地实现。

"storage-neutral"（存储中立）意味着将来可以有远程实现——agent 树可以跨机器。配合第 9 章的远程执行环境和第 3 章的 WebSocket 传输，这条线的方向很清楚：分布式的 agent 编排。

ThreadSpawnEdgeStatus 是"边"的状态——这是一张真正的图，不只是父子指针。

八、agent-identity：给 agent 发身份

agent-identity crate（1000 行）的 import 列表很扎眼 [源码 agent-identity/src/lib.rs:1-25]：

use crypto_box::SecretKey as Curve25519SecretKey;
use ed25519_dalek::Signer as _;
use ed25519_dalek::SigningKey;
use ed25519_dalek::VerifyingKey;
use ed25519_dalek::pkcs8::DecodePrivateKey;
use ed25519_dalek::pkcs8::EncodePrivateKey;
use jsonwebtoken::Algorithm;
use jsonwebtoken::DecodingKey;

Ed25519 签名密钥 + Curve25519 加密密钥 + JWT。

这不是"给子 agent 起个名字"级别的身份，这是密码学身份：agent 有自己的密钥对，能签名，能被验证，能拿到 JWT。

配合 workload-identity（870 行）这个 crate 名——这是云原生的工作负载身份概念。

意味着：一个 agent 可以向外部服务证明"我是某个用户会话下的某个子 agent"，而不必共享用户的凭据。第 5 章的 ModelClient 里那个 agent_identity_policy: AgentIdentityAuthPolicy 字段就是这条线的落点。

这是最小权限原则在 agent 编排上的应用。 也是本章看到的、Codex 走得最远的一步——它在为"agent 作为独立的安全主体"做准备。

九、和 dsh 四种委派机制的对照

dsh 教程第 11 章讲了四种：spawn（子 agent）、fork（分叉）、workflow（编排）、ralph（循环）。

最大的差别在"编排"这一格：dsh 把它做成一个可配置的 workflow 插件（声明式的图），Codex 把它做成提示词层的行为规范（让模型自己决定派几个、怎么派）。

两种做法的取舍很清楚：

• 声明式 workflow：可预测、可复现、可审计，但只能表达你预先想到的流程
• 提示词编排：灵活、能处理没预料到的任务分解，但不可预测、难复现

Codex 选了后者，然后用 AgentRegistry 的硬上限兜住最坏情况。这个组合（自由的策略 + 硬性的资源上限）在本教程里已经出现了第三次——第 5 章的重试上限、第 11 章的 Guardian 熔断器、这里的 agent 计数。

十、动手复核

cd codex/codex-rs

# 1. 两代工具集对比
ls core/src/tools/handlers/multi_agents/
ls core/src/tools/handlers/multi_agents_v2/

# 2. 协调者提示词（4972 字节，建议完整读）
cat core/templates/agents/orchestrator.md

# 3. 注册表的限制语义
sed -n '18,50p' core/src/agent/registry.rs

# 4. 角色只能收缩不能扩张
sed -n '1,10p' core/src/agent/role.rs
sed -n '36,60p' core/src/agent/role.rs

# 5. 拓扑存储
cat agent-graph-store/src/lib.rs

# 6. 密码学身份用了什么
sed -n '1,30p' agent-identity/src/lib.rs

# 7. 多 agent 相关的上下文片段
ls core/src/context/ | grep -E 'agent'

# 8. 多 agent 代码总量
for p in core/src/agent core/src/tools/handlers/multi_agents core/src/tools/handlers/multi_agents_v2 agent-graph-store agent-identity; do
  echo -n "$p: "; find $p -name '*.rs' -print0 2>/dev/null | xargs -0 cat | wc -l
done

十一、总结

1. 两代并存，版本持久化在会话元数据里——恢复老会话仍按老版本跑。V1 的动词是"控制"（spawn/send_input/close），V2 是"协作"（send_message/followup_task/list_agents）
2. "Do not perform the actual work while they are working" —— 主 agent 派活后只协调不干活，这条写在 orchestrator 提示词里，解决"主 agent 闲不住又干一遍"的失败模式
3. 一个 agent 就是一个新 Session，拿到的是父历史的截断分叉，复用第 12 章的分叉机制
4. AgentRegistry 限制累计总数（不是并发数），防止"关一个开一个"绕过；随机不重复的昵称是给人看的
5. 角色只能收缩不能扩张——"Roles may reduce its capabilities, but never replace the parent session's authority"。这是多 agent 安全的核心不变量
6. 拓扑是独立的、存储中立的图，为跨机器编排留了口子
7. agent 有密码学身份（Ed25519 + Curve25519 + JWT），能向外部服务证明自己是谁而不共享用户凭据——最小权限原则在 agent 编排上的应用
8. 编排在提示词层而非配置层，灵活性换可预测性，用硬性资源上限兜底

下一章收尾：把 Pi、dsh、Codex 三种哲学摆在一起，看能带走什么。

Related Documents

• 第13章-扩展面-MCP技能钩子插件与CodeMode
• 第15章-设计精华-三种harness哲学对照
• 第12章-会话持久化-rollout与线程恢复 —— 子 agent 复用的分叉机制
• dsh 教程第 11 章 —— 四种委派机制的对照
• Pi 教程第 13 章 —— "刻意不做子 agent"的论证