multi-agent.md +0 −131 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
34To see it in action, try the following prompt on your project:
35
36```
37I 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.
381. Security issue
392. Code quality
403. Bugs
414. Race
425. Test flakiness
436. Maintainability of the code
44```
45
46## Managing sub-agents
47
48- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.
49- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.
50
51## Approvals and sandbox controls
52
53Sub-agents inherit your current sandbox policy, but they run with
54non-interactive approvals. If a sub-agent attempts an action that would require
55a new approval, that action fails and the error is surfaced in the parent
56workflow.
57
58You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.
59
60## Agent roles
61
62You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).
63
64Agent roles can be defined either in your local configuration (typically `~/.codex/config.toml`) or shared in a project-specific `.codex/config.toml`.
65
66Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a
67role-specific config file (`config_file`) when Codex spawns an agent with that role.
68
69Codex ships with built-in roles:
70
71- `default`
72- `worker`
73- `explorer`
74
75Each agent role can override your default configuration. Common settings to override for an agent role are:
76
77- `model` and `model_reasoning_effort` to select a specific model for your agent role
78- `sandbox_mode` to mark an agent as `read-only`
79- `developer_instructions` to give the agent role additional instructions without relying on the parent agent for passing them
80
81### Schema
82
83| Field | Type | Required | Purpose |
84| --- | --- | --- | --- |
85| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |
86| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |
87| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |
88| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |
89
90**Notes:**
91
92- Unknown fields in `[agents.<name>]` are rejected.
93- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.
94- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.
95- If Codex can’t load a role config file, agent spawns can fail until you fix the file.
96- Any configuration not set by the agent role will be inherited from the parent session.
97
98### Example agent roles
99
100Below is an example that overrides the definitions for the built-in `default` and `explorer` agent roles and defines a new `reviewer` role.
101
102Example `~/.codex/config.toml`:
103
104```
105[agents.default]
106description = "General-purpose helper."
107
108[agents.reviewer]
109description = "Find security, correctness, and test risks in code."
110config_file = "agents/reviewer.toml"
111
112[agents.explorer]
113description = "Fast codebase explorer for read-heavy tasks."
114config_file = "agents/custom-explorer.toml"
115```
116
117Example config file for the `reviewer` role (`~/.codex/agents/reviewer.toml`):
118
119```
120model = "gpt-5.3-codex"
121model_reasoning_effort = "high"
122developer_instructions = "Focus on high priority issues, write tests to validate hypothesis before flagging an issue. When finding security issues give concrete steps on how to reproduce the vulnerability."
123```
124
125Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):
126
127```
128model = "gpt-5.3-codex-spark"
129model_reasoning_effort = "medium"
130sandbox_mode = "read-only"
131```