concepts/subagents.md +92 −0 added
1# Subagents
2
3Codex can run subagent workflows by spawning specialized agents in parallel so
4they can explore, tackle, or analyze work concurrently.
5
6This page explains the core concepts and tradeoffs. For setup, agent configuration, and examples, see [Subagents](https://developers.openai.com/codex/subagents).
7
8## Why subagent workflows help
9
10Even 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.
11
12This is often described as:
13
14- **Context pollution**: useful information gets buried under noisy intermediate output.
15- **Context rot**: performance degrades as the conversation fills up with less relevant details.
16
17For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot).
18
19Subagent workflows help by moving noisy work off the main thread:
20
21- Keep the **main agent** focused on requirements, decisions, and final outputs.
22- Run specialized **subagents** in parallel for exploration, tests, or log analysis.
23- Return **summaries** from subagents instead of raw intermediate output.
24
25They can also save time when the work can run independently in parallel, and
26they make larger-shaped tasks more tractable by breaking them into bounded
27pieces. For example, Codex can split analysis of a multi-million-token
28document into smaller problems and return distilled takeaways to the main
29thread.
30
31As a starting point, use parallel agents for read-heavy tasks such as
32exploration, tests, triage, and summarization. Be more careful with parallel
33write-heavy workflows, because agents editing code at once can create
34conflicts and increase coordination overhead.
35
36## Core terms
37
38Codex uses a few related terms in subagent workflows:
39
40- **Subagent workflow**: A workflow where Codex runs parallel agents and combines their results.
41- **Subagent**: A delegated agent that Codex starts to handle a specific task.
42- **Agent thread**: The CLI thread for an agent, which you can inspect and switch between with `/agent`.
43
44## Triggering subagent workflows
45
46Codex doesn't spawn subagents automatically, and it should only use subagents when you
47explicitly ask for subagents or parallel agent work.
48
49In practice, manual triggering means using direct instructions such as
50"spawn two agents," "delegate this work in parallel," or "use one agent per
51point." Subagent workflows consume more tokens than comparable single-agent runs
52because each subagent does its own model and tool work.
53
54A good subagent prompt should explain how to divide the work, whether Codex
55should wait for all agents before continuing, and what summary or output to
56return.
57
58```text
59Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.
60```
61
62## Choosing models and reasoning
63
64Different agents need different model and reasoning settings.
65
66If you don't pin a model or `model_reasoning_effort`, Codex can choose a setup
67that balances intelligence, speed, and price for the task. It may favor
68`gpt-5.4-mini` for fast scans or a higher-effort `gpt-5.5` configuration for
69more demanding reasoning when that model is available. When you want finer
70control, steer that choice in your prompt or set `model` and
71`model_reasoning_effort` directly in the agent file.
72
73For most tasks in Codex, start with `gpt-5.5` when it is available. Continue
74 using `gpt-5.4` during the rollout if `gpt-5.5` is not yet available. Use
75 `gpt-5.4-mini` when you want a faster, lower-cost option for lighter subagent
76 work. If you have ChatGPT Pro and want near-instant text-only iteration,
77 `gpt-5.3-codex-spark` remains available in research preview.
78
79### Model choice
80
81- **`gpt-5.5`**: Start here for demanding agents when it is available. It is strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.
82- **`gpt-5.4`**: Use this when `gpt-5.5` is not yet available or when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.
83- **`gpt-5.4-mini`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.
84- **`gpt-5.3-codex-spark`**: If you have ChatGPT Pro, use this research preview model for near-instant, text-only iteration when latency matters more than broader capability.
85
86### Reasoning effort (`model_reasoning_effort`)
87
88- **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).
89- **`medium`**: A balanced default for most agents.
90- **`low`**: Use when the task is straightforward and speed matters most.
91
92Higher 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).