multi-agent.md +10 −3
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
7174- `default`- `default`: general-purpose fallback role.
7275- `worker`- `worker`: execution-focused role for implementation and fixes.
7376- `explorer`- `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.