multi-agent.md +0 −312 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, 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## Process CSV batches with sub-agents
55
56Use `spawn_agents_on_csv` when you have many similar tasks that map to one row per work item. Codex reads the CSV, spawns one worker sub-agent per row, waits for the full batch to finish, and exports the combined results to CSV.
57
58This works well for repeated audits such as:
59
60- reviewing one file, package, or service per row
61- checking a list of incidents, PRs, or migration targets
62- generating structured summaries for many similar inputs
63
64The tool accepts:
65
66- `csv_path` for the source CSV
67- `instruction` for the worker prompt template, using `{column_name}` placeholders
68- `id_column` when you want stable item ids from a specific column
69- `output_schema` when each worker should return a JSON object with a fixed shape
70- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control
71
72Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting a result, Codex marks that row with an error in the exported CSV.
73
74Example prompt:
75
76```
77Create /tmp/components.csv with columns path,owner and one row per frontend component.
78
79Then call spawn_agents_on_csv with:
80- csv_path: /tmp/components.csv
81- id_column: path
82- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result."
83- output_csv_path: /tmp/components-review.csv
84- output_schema: an object with required string fields path, risk, summary, and follow_up
85```
86
87When you run this through `codex exec`, Codex shows a single-line progress update on `stderr` while the batch is running. The exported CSV includes the original row data plus metadata such as `job_id`, `item_id`, `status`, `last_error`, and `result_json`.
88
89Related runtime settings:
90
91- `agents.max_threads` caps how many agent threads can stay open concurrently.
92- `agents.job_max_runtime_seconds` sets the default per-worker timeout for CSV fan-out jobs. A per-call `max_runtime_seconds` override takes precedence.
93- `sqlite_home` controls where Codex stores the SQLite-backed state used for agent jobs and their exported results.
94
95## Approvals and sandbox controls
96
97Sub-agents inherit your current sandbox policy.
98
99In interactive CLI sessions, approval requests can surface from inactive agent
100threads even while you are looking at the main thread. The approval overlay
101shows the source thread label, and you can press `o` to open that thread before
102you approve, reject, or answer the request.
103
104In non-interactive flows, or whenever a run can’t surface a fresh approval,
105an action that needs new approval fails and Codex surfaces the error back to the
106parent workflow.
107
108Codex also reapplies the parent turn’s live runtime overrides when it spawns a
109child. That includes sandbox and approval choices you set interactively during
110the session, such as `/approvals` changes or `--yolo`, even if the selected
111agent role loads a config file with different defaults.
112
113You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.
114
115## Agent roles
116
117You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).
118
119Define agent roles either in your local configuration (typically `~/.codex/config.toml`) or in a project-specific `.codex/config.toml`.
120
121Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a
122role-specific config file (`config_file`) when Codex spawns an agent with that role.
123
124Codex ships with built-in roles:
125
126- `default`: general-purpose fallback role.
127- `worker`: execution-focused role for implementation and fixes.
128- `explorer`: read-heavy codebase exploration role.
129- `monitor`: long-running command/task monitoring role (optimized for waiting/polling).
130
131Each agent role can override your default configuration. Common settings to override for an agent role are:
132
133- `model` and `model_reasoning_effort` to select a specific model for your agent role
134- `sandbox_mode` to mark an agent as `read-only`
135- `developer_instructions` to give the agent role extra instructions without relying on the parent agent to pass them
136
137### Schema
138
139| Field | Type | Required | Purpose |
140| --- | --- | --- | --- |
141| `agents.max_threads` | number | No | Concurrent open agent thread cap. |
142| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |
143| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |
144| `[agents.<name>]` | table | No | Role declaration. `<name>` becomes the `agent_type` when spawning an agent. |
145| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |
146| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |
147
148**Notes:**
149
150- Codex rejects unknown fields in `[agents.<name>]`.
151- `agents.max_threads` defaults to `6` when you leave it unset.
152- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.
153- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.
154- Codex resolves relative `config_file` paths relative to the `config.toml` file that defines the role.
155- Codex validates `agents.<name>.config_file` at config load time, and it must point to an existing file.
156- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.
157- If Codex can’t load a role config file, agent spawns can fail until you fix the file.
158- The agent inherits any configuration that the role doesn’t set from the parent session.
159
160### Example agent roles
161
162The 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.
163
164#### Example 1: PR review team
165
166This pattern splits review into three focused roles:
167
168- `explorer` maps the codebase and gathers evidence.
169- `reviewer` looks for correctness, security, and test risks.
170- `docs_researcher` checks framework or API documentation through a dedicated MCP server.
171
172Project config (`.codex/config.toml`):
173
174```
175[agents]
176max_threads = 6
177max_depth = 1
178
179[agents.explorer]
180description = "Read-only codebase explorer for gathering evidence before changes are proposed."
181config_file = "agents/explorer.toml"
182
183[agents.reviewer]
184description = "PR reviewer focused on correctness, security, and missing tests."
185config_file = "agents/reviewer.toml"
186
187[agents.docs_researcher]
188description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
189config_file = "agents/docs-researcher.toml"
190```
191
192`agents/explorer.toml`:
193
194```
195model = "gpt-5.3-codex-spark"
196model_reasoning_effort = "medium"
197sandbox_mode = "read-only"
198developer_instructions = """
199Stay in exploration mode.
200Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
201Prefer fast search and targeted file reads over broad scans.
202"""
203```
204
205`agents/reviewer.toml`:
206
207```
208model = "gpt-5.3-codex"
209model_reasoning_effort = "high"
210sandbox_mode = "read-only"
211developer_instructions = """
212Review code like an owner.
213Prioritize correctness, security, behavior regressions, and missing test coverage.
214Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
215"""
216```
217
218`agents/docs-researcher.toml`:
219
220```
221model = "gpt-5.3-codex-spark"
222model_reasoning_effort = "medium"
223sandbox_mode = "read-only"
224developer_instructions = """
225Use the docs MCP server to confirm APIs, options, and version-specific behavior.
226Return concise answers with links or exact references when available.
227Do not make code changes.
228"""
229
230[mcp_servers.openaiDeveloperDocs]
231url = "https://developers.openai.com/mcp"
232```
233
234This setup works well for prompts like:
235
236```
237Review 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.
238```
239
240#### Example 2: Frontend integration debugging team
241
242This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.
243
244Project config (`.codex/config.toml`):
245
246```
247[agents]
248max_threads = 6
249max_depth = 1
250
251[agents.explorer]
252description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
253config_file = "agents/explorer.toml"
254
255[agents.browser_debugger]
256description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
257config_file = "agents/browser-debugger.toml"
258
259[agents.worker]
260description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
261config_file = "agents/worker.toml"
262```
263
264`agents/explorer.toml`:
265
266```
267model = "gpt-5.3-codex-spark"
268model_reasoning_effort = "medium"
269sandbox_mode = "read-only"
270developer_instructions = """
271Map the code that owns the failing UI flow.
272Identify entry points, state transitions, and likely files before the worker starts editing.
273"""
274```
275
276`agents/browser-debugger.toml`:
277
278```
279model = "gpt-5.3-codex"
280model_reasoning_effort = "high"
281sandbox_mode = "workspace-write"
282developer_instructions = """
283Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
284Use browser tooling for screenshots, console output, and network evidence.
285Do not edit application code.
286"""
287
288[mcp_servers.chrome_devtools]
289url = "http://localhost:3000/mcp"
290startup_timeout_sec = 20
291```
292
293`agents/worker.toml`:
294
295```
296model = "gpt-5.3-codex"
297model_reasoning_effort = "medium"
298developer_instructions = """
299Own the fix once the issue is reproduced.
300Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
301"""
302
303[[skills.config]]
304path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
305enabled = false
306```
307
308This setup works well for prompts like:
309
310```
311Investigate 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.
312```