multi-agent.md +0 −129 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
7## Enable multi-agent
8
9Multi-agent workflows are currently experimental and need to be explicitly enabled.
10
11You can enable this feature from the CLI with `/experimental`. Enable
12**Multi-agents**, then restart Codex.
13
14Multi-agent activity is currently surfaced in the CLI. Visibility in other
15surfaces (the Codex app and IDE Extension) is coming soon.
16
17You 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`):
18
19```
20[features]
21multi_agent = true
22```
23
24## Typical workflow
25
26Codex handles orchestration across agents, including spawning new sub-agents, routing follow-up instructions, waiting for results, and closing agent threads.
27
28When many agents are running, Codex waits until all requested results are available, then returns a consolidated response.
29
30Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.
31
32To see it in action, try the following prompt on your project:
33
34```
35I 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.
361. Security issue
372. Code quality
383. Bugs
394. Race
405. Test flakiness
416. Maintainability of the code
42```
43
44## Managing sub-agents
45
46- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.
47- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.
48
49## Approvals and sandbox controls
50
51Sub-agents inherit your current sandbox policy, but they run with
52non-interactive approvals. If a sub-agent attempts an action that would require
53a new approval, that action fails and the error is surfaced in the parent
54workflow.
55
56You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.
57
58## Agent roles
59
60You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).
61
62Agent roles can be defined either in your local configuration (typically `~/.codex/config.toml`) or shared in a project-specific `.codex/config.toml`.
63
64Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a
65role-specific config file (`config_file`) when Codex spawns an agent with that role.
66
67Codex ships with built-in roles:
68
69- `default`
70- `worker`
71- `explorer`
72
73Each agent role can override your default configuration. Common settings to override for an agent role are:
74
75- `model` and `model_reasoning_effort` to select a specific model for your agent role
76- `sandbox_mode` to mark an agent as `read-only`
77- `developer_instructions` to give the agent role additional instructions without relying on the parent agent for passing them
78
79### Schema
80
81| Field | Type | Required | Purpose |
82| --- | --- | --- | --- |
83| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |
84| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |
85| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |
86| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |
87
88**Notes:**
89
90- Unknown fields in `[agents.<name>]` are rejected.
91- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.
92- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.
93- If Codex can’t load a role config file, agent spawns can fail until you fix the file.
94- Any configuration not set by the agent role will be inherited from the parent session.
95
96### Example agent roles
97
98Below is an example that overrides the definitions for the built-in `default` and `explorer` agent roles and defines a new `reviewer` role.
99
100Example `~/.codex/config.toml`:
101
102```
103[agents.default]
104description = "General-purpose helper."
105
106[agents.reviewer]
107description = "Find security, correctness, and test risks in code."
108config_file = "agents/reviewer.toml"
109
110[agents.explorer]
111description = "Fast codebase explorer for read-heavy tasks."
112config_file = "agents/custom-explorer.toml"
113```
114
115Example config file for the `reviewer` role (`~/.codex/agents/reviewer.toml`):
116
117```
118model = "gpt-5.3-codex"
119model_reasoning_effort = "high"
120developer_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."
121```
122
123Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):
124
125```
126model = "gpt-5.3-codex-spark"
127model_reasoning_effort = "medium"
128sandbox_mode = "read-only"
129```