multi-agent.md Codex Docs, 2026-02-19 20:37 UTC → 2026-02-24 00:33 UTC

1# Multi-agents1# Multi-agents

2 2 

3Use experimental multi-agent collaboration in Codex CLI

4 

5Codex 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.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.

6 4 

7With multi-agent workflows you can also define your own set of agents with different model configurations and instructions depending on the agent.5With multi-agent workflows you can also define your own set of agents with different model configurations and instructions depending on the agent.

8 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-agent9## Enable multi-agent

10 10 

11Multi-agent workflows are currently experimental and need to be explicitly enabled.11Multi-agent workflows are currently experimental and need to be explicitly enabled.

31 31 

32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.

33 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 

34To see it in action, try the following prompt on your project:36To see it in action, try the following prompt on your project:

35 37 

36```38```

47 49 

48- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.50- 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.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).

50 53 

51## Approvals and sandbox controls54## Approvals and sandbox controls

52 55 

68 71 

69Codex ships with built-in roles:72Codex ships with built-in roles:

70 73 

71- `default`74- `default`: general-purpose fallback role.

72- `worker`75- `worker`: execution-focused role for implementation and fixes.

73- `explorer`76- `explorer`: read-heavy codebase exploration role.

77- `monitor`: long-running command/task monitoring role (optimized for waiting/polling).

74 78 

75Each agent role can override your default configuration. Common settings to override for an agent role are:79Each agent role can override your default configuration. Common settings to override for an agent role are:

76 80 

83| Field | Type | Required | Purpose |87| Field | Type | Required | Purpose |

84| --- | --- | --- | --- |88| --- | --- | --- | --- |

85| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |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). |

86| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |91| `[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. |92| `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. |93| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |

90**Notes:**95**Notes:**

91 96 

92- Unknown fields in `[agents.<name>]` are rejected.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.

93- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.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.

94- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.101- 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.102- 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.103- Any configuration not set by the agent role will be inherited from the parent session.