multi-agent.md +0 −257 deleted
File DeletedView Diff
1# Multi-agents
2
3Codex can run multi-agent workflows by spawning specialized agents in parallel and then collecting their results in one response. This can be particularly helpful for complex tasks that are highly parallel, such as codebase exploration or implementing a multi-step feature plan.
4
5With multi-agent workflows you can also define your own set of agents with different model configurations and instructions depending on the agent.
6
7For the concepts and tradeoffs behind multi-agent workflows (including context pollution/context rot and model-selection guidance), see [Multi-agents concepts](https://developers.openai.com/codex/concepts/multi-agents).
8
9## Enable multi-agent
10
11Multi-agent workflows are currently experimental and need to be explicitly enabled.
12
13You can enable this feature from the CLI with `/experimental`. Enable
14**Multi-agents**, then restart Codex.
15
16Multi-agent activity is currently surfaced in the CLI. Visibility in other
17surfaces (the Codex app and IDE Extension) is coming soon.
18
19You can also add the [`multi_agent` feature flag](https://developers.openai.com/codex/config-basic#feature-flags) directly to your configuration file (`~/.codex/config.toml`):
20
21```
22[features]
23multi_agent = true
24```
25
26## Typical workflow
27
28Codex handles orchestration across agents, including spawning new sub-agents, routing follow-up instructions, waiting for results, and closing agent threads.
29
30When many agents are running, Codex waits until all requested results are available, then returns a consolidated response.
31
32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.
33
34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, which is tuned for waiting and repeated status checks.
35
36To see it in action, try the following prompt on your project:
37
38```
39I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
401. Security issue
412. Code quality
423. Bugs
434. Race
445. Test flakiness
456. Maintainability of the code
46```
47
48## Managing sub-agents
49
50- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.
51- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.
52- The `wait` tool supports long polling windows for monitoring workflows (up to 1 hour per call).
53
54## Approvals and sandbox controls
55
56Sub-agents inherit your current sandbox policy, but they run with
57non-interactive approvals. If a sub-agent attempts an action that would require
58a new approval, that action fails and the error is surfaced in the parent
59workflow.
60
61You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.
62
63## Agent roles
64
65You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).
66
67Agent roles can be defined either in your local configuration (typically `~/.codex/config.toml`) or shared in a project-specific `.codex/config.toml`.
68
69Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a
70role-specific config file (`config_file`) when Codex spawns an agent with that role.
71
72Codex ships with built-in roles:
73
74- `default`: general-purpose fallback role.
75- `worker`: execution-focused role for implementation and fixes.
76- `explorer`: read-heavy codebase exploration role.
77- `monitor`: long-running command/task monitoring role (optimized for waiting/polling).
78
79Each agent role can override your default configuration. Common settings to override for an agent role are:
80
81- `model` and `model_reasoning_effort` to select a specific model for your agent role
82- `sandbox_mode` to mark an agent as `read-only`
83- `developer_instructions` to give the agent role additional instructions without relying on the parent agent for passing them
84
85### Schema
86
87| Field | Type | Required | Purpose |
88| --- | --- | --- | --- |
89| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |
90| `agents.max_depth` | number | No | Maximum nesting depth for spawned agent threads (root session starts at 0). |
91| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |
92| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |
93| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |
94
95**Notes:**
96
97- Unknown fields in `[agents.<name>]` are rejected.
98- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.
99- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.
100- `agents.<name>.config_file` is validated at config load time and must point to an existing file.
101- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.
102- If Codex can’t load a role config file, agent spawns can fail until you fix the file.
103- Any configuration not set by the agent role will be inherited from the parent session.
104
105### Example agent roles
106
107The best role definitions are narrow and opinionated. Give each role one clear job, a tool surface that matches that job, and instructions that keep it from drifting into adjacent work.
108
109#### Example 1: PR review team
110
111This pattern splits review into three focused roles:
112
113- `explorer` maps the codebase and gathers evidence.
114- `reviewer` looks for correctness, security, and test risks.
115- `docs_researcher` checks framework or API documentation through a dedicated MCP server.
116
117Project config (`.codex/config.toml`):
118
119```
120[agents]
121max_threads = 6
122max_depth = 1
123
124[agents.explorer]
125description = "Read-only codebase explorer for gathering evidence before changes are proposed."
126config_file = "agents/explorer.toml"
127
128[agents.reviewer]
129description = "PR reviewer focused on correctness, security, and missing tests."
130config_file = "agents/reviewer.toml"
131
132[agents.docs_researcher]
133description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
134config_file = "agents/docs-researcher.toml"
135```
136
137`agents/explorer.toml`:
138
139```
140model = "gpt-5.3-codex-spark"
141model_reasoning_effort = "medium"
142sandbox_mode = "read-only"
143developer_instructions = """
144Stay in exploration mode.
145Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
146Prefer fast search and targeted file reads over broad scans.
147"""
148```
149
150`agents/reviewer.toml`:
151
152```
153model = "gpt-5.3-codex"
154model_reasoning_effort = "high"
155sandbox_mode = "read-only"
156developer_instructions = """
157Review code like an owner.
158Prioritize correctness, security, behavior regressions, and missing test coverage.
159Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
160"""
161```
162
163`agents/docs-researcher.toml`:
164
165```
166model = "gpt-5.3-codex-spark"
167model_reasoning_effort = "medium"
168sandbox_mode = "read-only"
169developer_instructions = """
170Use the docs MCP server to confirm APIs, options, and version-specific behavior.
171Return concise answers with links or exact references when available.
172Do not make code changes.
173"""
174
175[mcp_servers.openaiDeveloperDocs]
176url = "https://developers.openai.com/mcp"
177```
178
179This setup works well for prompts like:
180
181```
182Review this branch against main. Have explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.
183```
184
185#### Example 2: frontend integration debugging team
186
187This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.
188
189Project config (`.codex/config.toml`):
190
191```
192[agents]
193max_threads = 6
194max_depth = 1
195
196[agents.explorer]
197description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
198config_file = "agents/explorer.toml"
199
200[agents.browser_debugger]
201description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
202config_file = "agents/browser-debugger.toml"
203
204[agents.worker]
205description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
206config_file = "agents/worker.toml"
207```
208
209`agents/explorer.toml`:
210
211```
212model = "gpt-5.3-codex-spark"
213model_reasoning_effort = "medium"
214sandbox_mode = "read-only"
215developer_instructions = """
216Map the code that owns the failing UI flow.
217Identify entry points, state transitions, and likely files before the worker starts editing.
218"""
219```
220
221`agents/browser-debugger.toml`:
222
223```
224model = "gpt-5.3-codex"
225model_reasoning_effort = "high"
226sandbox_mode = "workspace-write"
227developer_instructions = """
228Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
229Use browser tooling for screenshots, console output, and network evidence.
230Do not edit application code.
231"""
232
233[mcp_servers.chrome_devtools]
234url = "http://localhost:3000/mcp"
235startup_timeout_sec = 20
236```
237
238`agents/worker.toml`:
239
240```
241model = "gpt-5.3-codex"
242model_reasoning_effort = "medium"
243developer_instructions = """
244Own the fix once the issue is reproduced.
245Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
246"""
247
248[[skills.config]]
249path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
250enabled = false
251```
252
253This setup works well for prompts like:
254
255```
256Investigate why the settings modal fails to save. Have browser_debugger reproduce it, explorer trace the responsible code path, and worker implement the smallest fix once the failure mode is clear.
257```