multi-agent.md Codex Docs, 2026-02-20 12:16 UTC → 2026-02-24 06:27 UTC

4 4 

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

6 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 

7## Enable multi-agent9## Enable multi-agent

8 10 

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

29 31 

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

31 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 

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

33 37 

34```38```

45 49 

46- 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.

47- 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).

48 53 

49## Approvals and sandbox controls54## Approvals and sandbox controls

50 55 

66 71 

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

68 73 

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

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

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

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

72 78 

73Each 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:

74 80 

81| Field | Type | Required | Purpose |87| Field | Type | Required | Purpose |

82| --- | --- | --- | --- |88| --- | --- | --- | --- |

83| `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). |

84| `[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. |

85| `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. |

86| `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. |

88**Notes:**95**Notes:**

89 96 

90- 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.

91- 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.

92- 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.

93- 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.

94- 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.