Multi-Agent

Abstract

Multi-Agent Architecture 解决的是“什么时候把工作交给子 Agent，以及子 Agent 如何隔离、通信和回传结果”的问题。

Codex CLI 更强调 并行子 Agent 工作流：把探索、测试、日志分析等 noisy work 从主线程移出去，最后返回摘要
Claude Code 更强调 可配置 subagent：每个 subagent 有独立上下文、专门提示词、工具权限，并可选择 worktree 隔离

背景

即使模型上下文窗口很大，主会话仍然容易被中间输出污染：搜索结果、日志、测试输出、错误栈和探索性笔记会把真正重要的需求、约束和决策淹没。

Subagent 的价值在于把这些“嘈杂但必要”的工作移出主上下文：

并行独立任务：例如同时检查安全风险、测试缺口和可维护性问题
探索任务：让子 Agent 搜索代码库，主 Agent 只接收摘要
委托任务：把边界清晰的小任务交给专门 Agent
上下文保护：避免大型日志、搜索结果、文件内容进入主对话

Codex：In-Process Agent Tree

Codex 的 subagent 工作流更像一个主 Agent 管理多个子 Agent 的树形结构。主 Agent 可以根据用户明确指令，把任务拆给多个子 Agent 并行执行，然后等待它们返回结果。

触发方式

Codex 官方文档强调：Codex 不会自动生成 subagents，通常需要用户明确要求，例如“spawn two agents”“delegate this work in parallel”“use one agent per point”。

Architecture

Codex 的实现可以概括为同一进程内的 agent tree：

AgentControl：控制平面，用于启动、关闭、等待和管理子 Agent
AgentRegistry：记录已启动 Agent 的层级关系和生命周期
Agent Thread：每个子 Agent 都有自己的线程 / session 视角，可被查看和切换
Mailbox / Channels：用于 Agent 之间的异步通信和结果传递

Parent Agent
    ├── spawn_agent → Child Agent 1
    ├── spawn_agent → Child Agent 2
    └── spawn_agent → Child Agent 3

Spawning

Codex 的子 Agent 可以从父 Agent 的上下文中 fork 出来。fork 的范围可以根据任务调整，例如使用完整历史，或只带最近若干轮上下文。

Parent Agent
    ├── spawn_agent（完整历史）      → Child Agent 1
    ├── spawn_agent（最近 N 轮）     → Child Agent 2
    └── spawn_agent（无 / 少量上下文）→ Child Agent 3

每个 child agent 通常具备：

独立的 session / turn 管理
从父 Agent 派生出来的任务说明
可选的 forked history，用于携带背景上下文
自己的模型调用和工具执行过程
通过 registry / wait 机制向父 Agent 返回结果

Communication

Codex 的 multi-agent 模式更强调父子结构下的协作：

父 Agent 负责拆分任务、启动子 Agent、等待结果
子 Agent 独立执行自己的任务
结果通过 registry / wait 机制汇总回父 Agent
在更复杂实现中，可以通过 mailbox / channel 进行 Agent 间消息传递

Depth Control

Subagent 能带来并行能力，也会带来 token、成本和协调复杂度。因此 Codex 需要控制 agent 数量和层级，避免无限递归或过量并发。

常见约束包括：

最大 agent 数量
最大派生深度
子 Agent 是否允许继续生成子 Agent
子 Agent 使用的模型和 reasoning effort

Code Location

Agent control：codex-rs/core/src/agent/
Multi-agent handlers：codex-rs/core/src/tools/handlers/multi_agents/
Multi-agent v2 handlers：codex-rs/core/src/tools/handlers/multi_agents_v2/
Codex subagents docs：Subagents - Codex

Claude Code：Configurable Subagents

Claude Code 的 subagent 更像可配置的专门助手。每个 subagent 有自己的名称、描述、系统提示词、工具权限和独立上下文窗口。主 Agent 可以自动或显式地把任务委托给合适的 subagent。

Architecture

Claude Code 官方文档中，subagent 的核心特征是：

独立上下文窗口：避免污染主会话
自定义 system prompt：让 subagent 专注于特定角色
工具权限控制：可以限制 subagent 可使用的工具
项目级 / 用户级配置：subagent 可以在项目内或用户全局复用
可选 worktree isolation：让 subagent 在单独 git worktree 中修改文件

Main Claude Session
    ├── Delegate task → code-reviewer subagent
    ├── Delegate task → test-runner subagent
    └── Delegate task → debugger subagent

Configuration

Claude Code 的 subagent 通常以 Markdown 文件配置，包含 YAML frontmatter 和正文提示词。

---
name: code-reviewer
description: Review code quality, security, and maintainability
tools: Read, Grep, Glob
---

You are a focused code review subagent.
Review the assigned changes and return concise findings.

项目级 subagents 通常位于：

.claude/agents/

用户级 subagents 通常位于：

~/.claude/agents/

项目级配置优先级更高，适合团队共享；用户级配置适合个人常用角色。

Spawning / Delegation

Claude Code 可以根据 subagent 的 description 自动委托，也可以由用户显式指定：

请使用 code-reviewer subagent 检查最近的改动
请让 test-runner subagent 调查失败测试

每个 subagent：

在自己的上下文窗口中工作
接收主 Agent 分配的任务说明
使用自己被允许的工具集
完成后把摘要或结果返回主会话

上下文隔离

Claude Code subagent 的重点不是继承完整主会话历史，而是用独立上下文完成边界清晰的任务。这有利于保护主上下文，但也要求任务说明足够明确。

Worktree Isolation

Claude Code 支持通过 isolation: worktree 让 subagent 在单独 git worktree 中工作。这样多个 Agent 可以并行修改代码，而不直接互相覆盖同一个 checkout。

---
name: feature-worker
description: Implement isolated feature changes
isolation: worktree
---

这种隔离适合：

多个 Agent 并行实现不同方案
让 Agent 尝试较大改动，但不污染当前工作区
对比不同实现路径

代价是需要额外处理合并、冲突和最终采纳哪个 worktree 的结果。

Communication

Claude Code 的常规 subagent 更像“委托-返回”的模型：

主会话把任务交给 subagent
subagent 独立完成工作
subagent 返回结果摘要
主会话继续整合结果

在普通 subagent 模式下，重点是上下文隔离和任务委托；如果启用更高级的 agent teams，则可以出现更强的协作和直接消息能力。

对比

维度	Codex CLI	Claude Code
架构形态	进程内 agent tree / agent threads	可配置 subagents / agent teams
隔离方式	同一运行时内的子 Agent	独立上下文窗口，可选 worktree 隔离
上下文	可 fork 父 Agent 历史或部分历史	独立上下文，依赖任务说明和 subagent prompt
通信方式	父 Agent 启动、等待、汇总结果；可有 channel/mailbox 机制	常规模式为委托-返回；agent teams 可更强协作
并行成本	async task / agent thread 成本较低，但共享运行时	独立上下文和可选 worktree 带来更强隔离，也有更高成本
文件隔离	默认共享 workspace，需要协调写入	可通过 `isolation: worktree` 隔离文件修改
适用任务	读密集探索、测试、日志分析、摘要	专门角色、团队流程、并行改动、上下文隔离
主要风险	子 Agent 过多导致成本、上下文和生命周期复杂	任务说明不足、worktree 合并成本、工具权限配置复杂

Tradeoffs

Codex 的进程内 agent tree

启动成本低，适合快速并行探索
可以携带父 Agent 的上下文，子 Agent 更了解当前任务背景
父 Agent 更容易统一等待和汇总结果
共享 workspace 时要小心并行写入冲突
子 Agent 生命周期、数量和深度需要被严格控制

Claude Code 的 configurable subagents

每个 subagent 有独立上下文，能保护主会话
可以用专门 prompt 和工具权限塑造角色
worktree 隔离适合并行改代码和方案试验
子 Agent 不一定继承完整背景，任务说明必须清楚
多个 worktree 或多个专门 Agent 会带来合并和治理成本

适用场景

两类 Agent 都适合在这些场景使用 subagents：

并行独立任务：多个文件、多个模块、多个问题维度可以同时分析
探索性工作：搜索代码、阅读日志、跑测试，不污染主上下文
专门角色：安全审查、性能分析、测试修复、文档整理
上下文保护：把大量中间结果压缩成摘要返回
方案比较：让多个 Agent 走不同实现路径，再由主 Agent 比较

不适合使用 subagents 的情况

任务很小，单 Agent 更快
多个子任务强依赖同一批文件，容易写入冲突
需求尚不清晰，拆分后会放大误解
成本、延迟或上下文预算很紧

小结

Multi-agent 架构不是为了“让 Agent 看起来更聪明”，而是为了管理复杂任务中的并行性和上下文污染。

Codex 更偏向在同一运行时里生成并行子 Agent，用较低成本完成探索和分析；Claude Code 更偏向把 subagent 做成可配置角色，用独立上下文、工具权限和 worktree 隔离来组织复杂工作流。

关键差异是：Codex 子 Agent 更容易共享任务背景，Claude Code subagent 更强调上下文隔离和角色化配置。