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