multi-agent.md Codex Docs, 2026-03-07 00:33 UTC → 2026-03-11 00:31 UTC

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.34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, tuned for waiting and repeated status checks.

35 35 

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

37 37 

53 53 

54## Process CSV batches with sub-agents54## Process CSV batches with sub-agents

55 55 

56Use `spawn_agents_on_csv` when you have many similar tasks that can be expressed as 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.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 57 

58This works well for repeated audits such as:58This works well for repeated audits such as:

59 59 

69- `output_schema` when each worker should return a JSON object with a fixed shape69- `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 control70- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control

71 71 

72Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting a result, that row is marked as failed in the exported CSV.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 73 

74Example prompt:74Example prompt:

75 75 

101shows the source thread label, and you can press `o` to open that thread before101shows the source thread label, and you can press `o` to open that thread before

102you approve, reject, or answer the request.102you approve, reject, or answer the request.

103 103 

104In non-interactive flows, or whenever a run cannot surface a fresh approval,104In non-interactive flows, or whenever a run can’t surface a fresh approval,

105an action that needs new approval fails and the error is surfaced back to the105an action that needs new approval fails and Codex surfaces the error back to the

106parent workflow.106parent workflow.

107 107 

108Codex also reapplies the parent turn’s live runtime overrides when it spawns a108Codex also reapplies the parent turn’s live runtime overrides when it spawns a

116 116 

117You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).117You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).

118 118 

119Agent roles can be defined either in your local configuration (typically `~/.codex/config.toml`) or shared in a project-specific `.codex/config.toml`.119Define agent roles either in your local configuration (typically `~/.codex/config.toml`) or in a project-specific `.codex/config.toml`.

120 120 

121Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a121Each 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.122role-specific config file (`config_file`) when Codex spawns an agent with that role.

132 132 

133- `model` and `model_reasoning_effort` to select a specific model for your agent role133- `model` and `model_reasoning_effort` to select a specific model for your agent role

134- `sandbox_mode` to mark an agent as `read-only`134- `sandbox_mode` to mark an agent as `read-only`

135- `developer_instructions` to give the agent role additional instructions without relying on the parent agent for passing them135- `developer_instructions` to give the agent role extra instructions without relying on the parent agent to pass them

136 136 

137### Schema137### Schema

138 138 

139| Field | Type | Required | Purpose |139| Field | Type | Required | Purpose |

140| --- | --- | --- | --- |140| --- | --- | --- | --- |

141| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |141| `agents.max_threads` | number | No | Concurrent open agent thread cap. |

142| `agents.max_depth` | number | No | Maximum nesting depth for spawned agent threads (root session starts at 0). |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. |143| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |

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

147 147 

148**Notes:**148**Notes:**

149 149 

150- Unknown fields in `[agents.<name>]` are rejected.150- Codex rejects unknown fields in `[agents.<name>]`.

151- `agents.max_threads` defaults to `6` when you leave it unset.

151- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.152- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.

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

153- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.154- Codex resolves relative `config_file` paths relative to the `config.toml` file that defines the role.

154- `agents.<name>.config_file` is validated at config load time and must point to an existing file.155- Codex validates `agents.<name>.config_file` at config load time, and it must point to an existing file.

155- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.156- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.

156- If Codex can’t load a role config file, agent spawns can fail until you fix the file.157- If Codex can’t load a role config file, agent spawns can fail until you fix the file.

157- Any configuration not set by the agent role will be inherited from the parent session.158- The agent inherits any configuration that the role doesn’t set from the parent session.

158 159 

159### Example agent roles160### Example agent roles

160 161 

236Review 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.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.

237```238```

238 239 

239#### Example 2: frontend integration debugging team240#### Example 2: Frontend integration debugging team

240 241 

241This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.242This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.

242 243