multi-agent.md Codex Docs, 2026-02-24 06:27 UTC → 2026-03-03 00:35 UTC

104 104 

105### Example agent roles105### Example agent roles

106 106 

107Below is an example that overrides the definitions for the built-in `default` and `explorer` agent roles and defines a new `reviewer` role.107The best role definitions are narrow and opinionated. Give each role one clear job, a tool surface that matches that job, and instructions that keep it from drifting into adjacent work.

108 108 

109Example `~/.codex/config.toml`:109#### Example 1: PR review team

110 

111This pattern splits review into three focused roles:

112 

113- `explorer` maps the codebase and gathers evidence.

114- `reviewer` looks for correctness, security, and test risks.

115- `docs_researcher` checks framework or API documentation through a dedicated MCP server.

116 

117Project config (`.codex/config.toml`):

110 118 

111```119```

112[agents.default]120[agents]

113description = "General-purpose helper."121max_threads = 6

122max_depth = 1

123 

124[agents.explorer]

125description = "Read-only codebase explorer for gathering evidence before changes are proposed."

126config_file = "agents/explorer.toml"

114 127 

115[agents.reviewer]128[agents.reviewer]

116description = "Find security, correctness, and test risks in code."129description = "PR reviewer focused on correctness, security, and missing tests."

117config_file = "agents/reviewer.toml"130config_file = "agents/reviewer.toml"

118 131 

119[agents.explorer]132[agents.docs_researcher]

120description = "Fast codebase explorer for read-heavy tasks."133description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

121config_file = "agents/custom-explorer.toml"134config_file = "agents/docs-researcher.toml"

135```

136 

137`agents/explorer.toml`:

138 

139```

140model = "gpt-5.3-codex-spark"

141model_reasoning_effort = "medium"

142sandbox_mode = "read-only"

143developer_instructions = """

144Stay in exploration mode.

145Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.

146Prefer fast search and targeted file reads over broad scans.

147"""

122```148```

123 149 

124Example config file for the `reviewer` role (`~/.codex/agents/reviewer.toml`):150`agents/reviewer.toml`:

125 151 

126```152```

127model = "gpt-5.3-codex"153model = "gpt-5.3-codex"

128model_reasoning_effort = "high"154model_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."155sandbox_mode = "read-only"

156developer_instructions = """

157Review code like an owner.

158Prioritize correctness, security, behavior regressions, and missing test coverage.

159Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.

160"""

130```161```

131 162 

132Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):163`agents/docs-researcher.toml`:

133 164 

134```165```

135model = "gpt-5.3-codex-spark"166model = "gpt-5.3-codex-spark"

136model_reasoning_effort = "medium"167model_reasoning_effort = "medium"

137sandbox_mode = "read-only"168sandbox_mode = "read-only"

169developer_instructions = """

170Use the docs MCP server to confirm APIs, options, and version-specific behavior.

171Return concise answers with links or exact references when available.

172Do not make code changes.

173"""

174 

175[mcp_servers.openaiDeveloperDocs]

176url = "https://developers.openai.com/mcp"

177```

178 

179This setup works well for prompts like:

180 

181```

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

183```

184 

185#### Example 2: frontend integration debugging team

186 

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

188 

189Project config (`.codex/config.toml`):

190 

191```

192[agents]

193max_threads = 6

194max_depth = 1

195 

196[agents.explorer]

197description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."

198config_file = "agents/explorer.toml"

199 

200[agents.browser_debugger]

201description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."

202config_file = "agents/browser-debugger.toml"

203 

204[agents.worker]

205description = "Implementation-focused agent for small, targeted fixes after the issue is understood."

206config_file = "agents/worker.toml"

207```

208 

209`agents/explorer.toml`:

210 

211```

212model = "gpt-5.3-codex-spark"

213model_reasoning_effort = "medium"

214sandbox_mode = "read-only"

215developer_instructions = """

216Map the code that owns the failing UI flow.

217Identify entry points, state transitions, and likely files before the worker starts editing.

218"""

219```

220 

221`agents/browser-debugger.toml`:

222 

223```

224model = "gpt-5.3-codex"

225model_reasoning_effort = "high"

226sandbox_mode = "workspace-write"

227developer_instructions = """

228Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.

229Use browser tooling for screenshots, console output, and network evidence.

230Do not edit application code.

231"""

232 

233[mcp_servers.chrome_devtools]

234url = "http://localhost:3000/mcp"

235startup_timeout_sec = 20

236```

237 

238`agents/worker.toml`:

239 

240```

241model = "gpt-5.3-codex"

242model_reasoning_effort = "medium"

243developer_instructions = """

244Own the fix once the issue is reproduced.

245Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.

246"""

247 

248[[skills.config]]

249path = "/Users/me/.agents/skills/docs-editor/SKILL.md"

250enabled = false

251```

252 

253This setup works well for prompts like:

254 

255```

256Investigate why the settings modal fails to save. Have browser_debugger reproduce it, explorer trace the responsible code path, and worker implement the smallest fix once the failure mode is clear.

138```257```