How Codex Implements Multi-Agent Collaboration: Independent Sessions, Context Handoff, and Async Coordination

01 | Why Split Work Across Multiple Agents?

A single agent fixing a bug must read code, check configs, investigate test failures, modify, then re-verify. Stuffing all that into one session creates two problems: time and context.

Time: Some tasks are independent. During a code review, one sub-agent can investigate test failures while another checks broken doc links — they can run in parallel.

Context: Code, configs, logs, and failed attempts accumulate in one session. A dedicated test-investigation agent keeps its context focused on the test problem.

But finer splits aren't always better. The parent agent must brief context, sub-agents must read materials and call models, and results must be merged. A task solvable by reading one file may incur more handoff overhead than actual work if split into three. Dependencies also matter: if test-failure cause is unknown, letting another agent modify code on a guess often causes rework. The solution: dispatch read-only investigation first, then modify after cause is clear, then verify. The parent can work on independent tasks while waiting.

02 | Collaboration Patterns and Codex's Choice

Fixed Workflow

Pre-defined steps: requirements agent → coding agent → testing agent. Program routes outputs. Easy to debug and validate at handoffs, but branching for retries or new investigations requires pre-planned branches or developer intervention. Suits stable processes; struggles with high variability.

Orchestrator-Workers (Primary Agent Scheduling)

Keep a primary agent that reads the project, decides what help is needed, dispatches sub-tasks, and aggregates results. The primary can add investigations on the fly, launch independent tasks in parallel, and integrate results. However, the primary's scheduling quality becomes critical: wrong splits cause duplicate work; unclear briefs yield unmergeable results; the primary must still judge which conclusions are trustworthy.

Handoff (Relay)

Current agent transfers control to another (e.g., support agent → refund agent). The receiver continues and replies to the user. Good for domain specialization, but multi-hop handoffs need clean context transfer. If final output needs synthesis, an integrator is still required.

Codex's Approach

Codex uses orchestrator-workers with recursive delegation. The root agent (primary) creates agent A; A can create agent C. Results flow upward: C → A → root. Siblings (A and B) can message each other directly without root relay. This fits programming because the primary often discovers new dependencies only after reading the codebase — it can then adjust delegation dynamically instead of pre-defining all steps.

03 | What Is a Dispatched Sub-Agent?

Creating a sub-agent is not a single model call. Codex spawns an independent session with its own conversation history and running state — a persistent work log of received requirements, read materials, and formed conclusions.

The sub-agent runs an agent loop : model decides next action → tools execute → results feed back to model → repeat. One "round" of work may contain multiple model calls and tool invocations. Later, the same sub-agent can be reused for a new round (e.g., review implementation) within the same session.

Codex reuses its existing session engine; a shared management layer creates sessions, records parent-child relationships, routes messages by agent name/ID, and coordinates execution resources. Each agent has its own history; tool results from agent A do not automatically become part of agent B's history. New user requirements received by the parent do not auto-appear in children. Synchronization happens only via explicit task briefs and message passing.

04 | Context Inheritance and Cleanup

Problem: User said "add a button, reuse existing styles, no new libs." Parent knows this. If child only receives "do the button part," it may pick a new component library or write fresh styles — functional but violates constraints.

Codex lets the dispatching agent choose how much history to inherit:

None: Child starts fresh; parent must re-brief all constraints.

All available history (default): Child receives full cleaned history.

Last N rounds: e.g., only the last two work rounds (a round = one complete investigate-read-conclude cycle, not two messages).

Cleanup before inheritance: Parent history contains in-progress tool calls, intermediate reasoning, progress updates, and inter-agent chatter. If copied raw, the child might continue the parent's ongoing work. Codex filters: keeps user messages, essential instructions, and assistant final answers; drops reasoning traces, non-final assistant messages, and routine tool calls/results. However, conclusions already written into final answers (e.g., "project has reusable button component") are preserved. If history was previously compressed (summarized key facts into a recovery point), the child may inherit that compressed version with its own retention rules.

Identity reset: Parent's team-role instructions ("you own end-to-end delivery") are stripped. Child receives new identity: its name, parent's name, how to contact teammates, and that final answer goes back to parent. Prior inter-agent messages are not copied, preventing stale requests from being mistaken as new tasks.

Task brief still required: History explains project context but not the child's specific scope. A vague "review the code" is insufficient; a proper brief specifies: what to check, read-only vs write permissions, and exact deliverables (locations, reasons, needed verifications). The brief defines goal, boundaries, and output format; history only reduces repeated explanations.

05 | Async Message Passing and Result Return

Scenario: Child discovers a reusable utility function while parent is about to re-implement it. Best to notify parent immediately to avoid rework.

Mechanism: Each agent has a pending-message queue . Sent messages (with sender, recipient, payload) are stored there. The sender continues working; the receiver processes queued messages on its next model input preparation. A model request already in flight cannot be altered. "Send success" only means Codex accepted and queued the message — not that the recipient has read or acted on it.

Message vs Follow-up Task: Adding "also check legacy config" to a working child uses a normal message (queued, processed next turn). Asking an idle child to "now review this change" is a follow-up task — it delivers the message and explicitly triggers a new work round. Normal messages won't wake an idle agent; follow-up tasks do (or queue until the agent can accept input).

Auto result return: When a child finishes a round, Codex packages its final answer as a message to the parent. The investigative process (dozens of file reads) stays in the child's session; parent receives only the conclusion. Parent must still evaluate correctness and evidence sufficiency; Codex does not auto-validate.

Late-arriving messages during parent wrap-up: If parent has entered final-response phase with no further work planned, ordinary collaboration messages are kept in the queue but do not automatically restart a reasoning round. They'll be processed when the user adds a new request or the model continues tool use. This prevents delivered answers from being endlessly extended by straggler messages.

06 | Waiting Without Polling

Parent needs results from children A and B. Polling every few seconds wastes model calls. Codex provides a wait tool : parent does independent work until it hits a dependency, then calls wait. The runtime monitors for new collaboration messages, user input, or timeout. Any arrival ends the wait and returns the reason (message received, user input, timeout). The wait tool does not return the children's full reports — those arrive as separate queued messages for the model to read next turn.

Wait ≠ all done: A's intermediate note "found a clue, still verifying" ends the wait even though A isn't finished. B's final result ends the wait. User's new instruction ends the wait. Parent must inspect what arrived and decide whether dependencies are satisfied.

Timeout: Only stops this wait; children keep working and are not cancelled.

Interrupt & reuse: If A's direction becomes obsolete, parent can interrupt A's current round. The session and history persist; file edits already made are not rolled back. Later, parent can re-task the same A (e.g., review the modified module) — A retains its prior investigation context. This creates a reusable work unit: accept task → execute → return result → idle → accept next task. Reuse preserves context but new task scope must still be clearly briefed.

Resource control: Two limits: (1) concurrent executing agents — new launches may be rejected at capacity; (2) resident sessions in memory — idle sessions can be persisted and unloaded, but active sessions or those with unprocessed messages cannot be evicted. Separating "round completion" from "session retention" enables both context reuse and memory management.

07 | Avoiding "More Agents, More Chaos"

Independent contexts share the working directory and filesystem . If A edits page header and B edits footer, both may read the old version and overwrite each other's writes. Context isolation doesn't prevent file-level conflicts.

Mitigations: restrict children to read-only investigation; let parent consolidate writes. For parallel writes, explicitly assign file ownership ranges and designate a single integrator per file.

Codex provides primitives (create agent, dispatch task, send message) but does not auto-resolve task decomposition, ownership assignment, or conflict arbitration. The model must judge based on goals, instructions, and incoming evidence. Example: child reports "tests passed" — parent must check which tests ran and whether they cover modified behaviors. Conflicting reviews require tracing back to code and verification results; message delivery alone doesn't substitute that judgment.

Multi-agent gains come from: independent progress, useful handoffs, and correct final integration. For tiny or tightly coupled tasks, a single session is simpler. The reusable lessons are the coordination mechanisms and explicit role definition.

Key Design Takeaways for Building Multi-Agent Systems

Continuous investigation: Sub-agents run full agent loops (model → tool → model), not one-shot Q&A. Reuse the same engine; give each participant isolated context and state.

Context continuity: Handoff must bundle necessary background and a concrete task brief. Clean parent's execution noise and old identity to prevent role confusion.

Async messaging: Agents progress at different speeds. Queue messages; wake waiters on new activity; distinguish informational messages, follow-up tasks, and result returns.

Decouple round completion from session lifetime: A finished round doesn't delete the work log; a saved log doesn't force the session to stay resident. This enables reuse and memory control.

Codex's runtime makes these coordination actions reliable. Whether the decomposition is sound and whether sub-agent conclusions are correct still depend on the model reasoning over task requirements, current evidence, and verification results. When designing your own agents, ask: Will context be lost after split? Can messages be received while busy? Can collaboration continue after a task ends? These are the engineering gaps beyond model inference.

Code example

来源丨
经授权
转自
小林coding（ID：CodingLin）
作者
丨
小林coding