Codex Subagents: Three Specialist Agents, One Synthesised Answer
In this article
Single-agent Codex workflows hit a natural ceiling when tasks span genuinely distinct problem domains simultaneously. A hands-on guide published in Towards Data Science by Shuai Guo on August 28, 2026 lays out the deliberate, practitioner-controlled version of Codex's subagent mechanic — one that gives engineers explicit authority over which specialist agents run, what they know, and how their outputs get reconciled. For teams moving beyond simple prompt-response loops, the pattern maps directly to the kind of pipeline architecture that is driving AI gains in 2026.
Agent Definition: TOML Files as the Contract Layer
Custom agents live as TOML files under .codex/agents/, alongside a project-level config.toml. Each TOML file requires exactly three fields: name (the identifier Codex uses internally), description (a plain-language summary of the agent's specialty), and developer_instructions (the behavioural directive the agent follows during execution).
Guo's travel-planning case study defines three agents. The travel_logistics agent is described as a "Travel specialist for comparing routes and journey convenience across candidate destinations," and its developer_instructions direct it to evaluate every destination from a travel-logistics perspective and return concise, source-backed findings to the main agent. The budget_analyst and experience_researcher agents follow an identical structural pattern, each scoped to a single evaluative lens — cost and experiential fit respectively. Beyond those three required fields, the spec supports optional overrides for model selection, reasoning effort, sandbox configuration, tools, and skills; absent any overrides, subagents inherit all of those settings from the main Codex session.
Parallelism is governed by a single config.toml directive:
[agents]
max_concurrent_threads_per_session = 3
That line allows up to three subagent threads to execute simultaneously, matching the number of specialists in this case study exactly.
Orchestration Flow and CLI Inspection
Launching the workflow requires only one flag — codex --search — which activates web search for the main session. Subagents inherit that capability automatically when spawned; no per-agent configuration is necessary. The task prompt carries the coordination logic: it names the three agents explicitly, instructs them to run in parallel, specifies that each must evaluate all three destinations (Lisbon, Prague, and Copenhagen) from its own specialty, and directs the main agent to wait for all three before synthesising a recommendation.
Once the prompt is submitted, Codex spawns all three specialist threads concurrently. Practitioners can observe per-thread activity in real time using the /agent CLI command, which opens an agent-thread view showing each specialist's context, tool calls, and intermediate results as they accumulate. Debugging a multi-agent workflow is considerably harder when thread-level state is opaque, and /agent eliminates that gap directly in the terminal.
The synthesis step is where the orchestrator earns its role. Each subagent reached a different conclusion independently — travel_logistics recommended Copenhagen, budget_analyst preferred Prague, and experience_researcher favoured Lisbon. The main agent aggregated all three reports and recommended Lisbon as the best balance across the traveller's stated criteria of convenient travel, museums, and local food. The final output was not a concatenation of the three reports; it was a judgment that weighted competing specialist findings against the original requirements. This distinction matters for anyone concerned about the four agent control layers that lack a shared contract — here, the main agent's synthesis prompt serves as that contract.
When to Use Subagents — and How to Encode the Pattern
| Invocation Method | Best Fit | Agent Definitions Still Required? |
|---|---|---|
| Explicit prompt instruction | One-off tasks where agent delegation is specified per run | Yes — .codex/agents/*.toml |
AGENTS.md project file |
Recurring project strategy where delegation applies across all sessions | Yes — .codex/agents/*.toml |
SKILL.md packaged instruction |
Recurrent task types that should trigger the subagent pattern automatically | Yes — .codex/agents/*.toml |
The critical architectural rule across all three methods: the TOML agent files always define who the subagents are, while the prompt, AGENTS.md, or skill instruction defines when and how they are invoked. Those are separate concerns, and conflating them breaks the abstraction. The subagent pattern is most defensible when the task contains several types of work that are genuinely independent — meaning subagents can complete their evaluations without waiting on each other — and a synthesis step meaningfully adds value over simply concatenating results.
The broader point is that deliberate multi-agent orchestration is becoming a first-class CLI primitive. Thread inspection, concurrent execution limits, and agent inheritance are all configurable from a project directory — without touching model weights or infrastructure — which reinforces the case that systems-level engineering now rivals scaling as a lever for capability gains.