concepts/multi-agents.md +53 −0 added
1# Multi-agents
2
3Codex can run multi-agent workflows by spawning specialized agents in parallel and collecting their results in one response.
4
5This page explains the core concepts and tradeoffs. For setup, agent configuration, and examples, see [Multi-agents](https://developers.openai.com/codex/multi-agent).
6
7## Why multi-agent workflows help
8
9Even with large context windows, models have limits. If you flood the main conversation (where you’re defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.
10
11This is often described as:
12
13- **Context pollution**: useful information gets buried under noisy intermediate output.
14- **Context rot**: performance degrades as the conversation fills up with less relevant details.
15
16For background, see Chroma’s writeup on [context rot](https://research.trychroma.com/context-rot).
17
18Multi-agent workflows help by moving noisy work off the main thread:
19
20- Keep the **main agent** focused on requirements, decisions, and final outputs.
21- Run specialized **sub-agents** in parallel for exploration, tests, or log analysis.
22- Return **summaries** from sub-agents instead of raw intermediate output.
23
24As a starting point, use parallel agents for tasks that mostly read (exploration, tests, triage, and summarization). Be more careful with parallel write-heavy workflows, because multiple agents editing code at once can create conflicts and increase coordination overhead.
25
26## Core terms
27
28Codex uses a few related terms in multi-agent workflows:
29
30- **Multi-agent**: A workflow where Codex runs multiple agents in parallel and combines their results.
31- **Sub-agent**: A delegated agent that Codex starts to handle a specific task.
32- **Agent thread**: The CLI thread for an agent, which you can inspect and switch between with `/agent`.
33
34## Choosing models and reasoning
35
36Different agents benefit from different model and reasoning settings.
37
38`gpt-5.3-codex-spark` is available in research preview for ChatGPT Pro
39subscribers. See [Models](https://developers.openai.com/codex/models) for current availability. If you’re
40using Codex via the API, use GPT-5.2-Codex today.
41
42### Model choice
43
44- **`gpt-5.3-codex`**: Use for agents that need stronger reasoning, such as code review, security analysis, multi-step implementation, or tasks with ambiguous requirements. The main agent and agents that propose or apply edits usually fit here.
45- **`gpt-5.3-codex-spark`**: Use for agents that prioritize speed over depth, such as exploration, read-heavy scans, or quick summarization tasks. Spark works well for parallel workers that return distilled results to the main agent.
46
47### Reasoning effort (`model_reasoning_effort`)
48
49- **`high`**: Use when an agent needs to trace complex logic, validate assumptions, or work through edge cases (for example, reviewer or security-focused agents).
50- **`medium`**: A balanced default for most agents.
51- **`low`**: Use when the task is straightforward and speed matters most.
52
53Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://developers.openai.com/codex/models), [Config basics](https://developers.openai.com/codex/config-basic), and [Configuration Reference](https://developers.openai.com/codex/config-reference).