# Mastering Multi-Agent Workflows with Codex: A Practical Guide to Subagents
## Understanding the Core Concept
Modern AI coding assistants are evolving beyond simple single-threaded task execution. When you assign a complex, multi-faceted problem to Codex, it doesn’t just tackle everything in one go. Instead, it has the ability to decompose the work into distinct, independent pieces and dispatch separate focused agents—known as subagents—to handle each piece simultaneously.
Think of it like managing a small team. The main agent acts as a project manager: it breaks down the problem, assigns roles, keeps track of progress, and synthesizes everyone’s contributions into a cohesive final deliverable. Each subagent, meanwhile, operates in its own isolated thread with a narrow focus, ensuring that specialized work gets the attention it deserves without interfering with other parallel efforts.
This architecture is particularly powerful when a single task spans multiple domains—like planning a trip that involves logistics, finance, and cultural research all at once. By distributing these concerns across dedicated agents, you get faster, more thorough, and more nuanced results than a single monolithic pass could ever deliver.
## A Hands-On Example: Planning the Perfect Trip
Let’s walk through a concrete scenario to make this concept tangible. Imagine you’re planning a four-day solo leisure trip departing from Zurich between October 15 and October 18, 2026. You have a firm budget of 1,200 Swiss Francs, and you care deeply about three things: easy and convenient travel, world-class museums, and authentic local cuisine. Your shortlist of destinations includes Lisbon, Prague, and Copenhagen.
To solve this with subagents, you first define three specialist agents, each with a clear domain of expertise:
– **Travel Logistics Agent** — evaluates routes, transit options, and journey convenience.
– **Budget Analyst** — estimates costs and ensures each destination fits within your spending limit.
– **Experience Researcher** — assesses how well each city matches your cultural and culinary interests.
### Setting Up the Specialist Agents
Codex lets you define custom agents on a per-project basis. You do this by creating TOML configuration files inside a `.codex/agents/` directory in your project folder. Each agent definition needs three key pieces of information:
1. **name** — a unique identifier Codex uses to reference the agent.
2. **description** — a brief explanation of what the agent specializes in.
3. **developer_instructions** — the behavioral guidelines that tell the agent how to approach its work.
Here is how you might define the Travel Logistics Agent:
“`toml
name = “travel_logistics”
description = “Travel specialist for comparing routes and journey convenience across candidate destinations.”
developer_instructions = “””
Evaluate every destination from a travel-logistics perspective.
Return concise, source-backed findings to the main agent.
“””
“`
The Budget Analyst follows the same pattern:
“`toml
name = “budget_analyst”
description = “Budget specialist for comparing the likely trip cost across candidate destinations.”
developer_instructions = “””
Evaluate every destination from a trip-budget perspective.
Return concise, source-backed findings to the main agent.
“””
“`
And the Experience Researcher:
“`toml
name = “experience_researcher”
description = “Destination specialist for comparing how well each option fits the traveler’s stated interests.”
developer_instructions = “””
Evaluate every destination against the traveler’s stated interests.
Return concise, source-backed findings to the main agent.
“””
“`
Each agent can also optionally override settings like the model it uses, reasoning depth, sandbox permissions, available tools, and skills. If you leave those unspecified, the subagents inherit the configuration from the main Codex session, keeping setup simple and consistent.
At the project level, you may also want to configure limits on how many subagent threads can run at the same time. This is done in `.codex/config.toml`:
“`toml
[agents]
max_concurrent_threads_per_session = 3
“`
This setting ensures that no more than three subagent threads execute simultaneously, which is exactly what we need for our three specialists.
### Running the Parallel Workflow
Once the agents are defined, you give the main agent your task prompt. The prompt explicitly names each specialist and instructs Codex to use them in parallel. For example:
> “I am planning a four-day solo leisure trip from Zurich from October 15 to October 18, 2026. My total budget is CHF 1,200. Compare Lisbon, Prague, and Copenhagen. I care about convenient travel, museums, and local food. Use the `travel_logistics`, `budget_analyst`, and `experience_researcher` agents in parallel. Each agent should evaluate all three destinations from its specialty. Wait for all three agents, then recommend one destination and explain the main tradeoffs with source links.”
When you submit this prompt, Codex spins up all three subagents at the same time. You can monitor each agent’s progress individually, watching their tool usage, context activity, and intermediate results in real time through the CLI thread view. This transparency is a major advantage—you can see exactly what each specialist is doing before the final synthesis begins.
### Reviewing the Output
After all three subagents complete their work, the main agent gathers their individual findings and performs a comparative analysis. In our scenario, the results were revealing: the Travel Logistics subagent favored Copenhagen for its excellent transit connections, the Budget Analyst recommended Prague for being the most cost-effective option, and the Experience Researcher landed on Lisbon for its unmatched museums and food scene.
Rather than simply picking one or pasting all three reports together, the main agent weighed each perspective against the original requirements—budget, convenience, museums, and cuisine—and ultimately recommended Lisbon as the best overall balance. This demonstrates that the main agent is doing genuine synthesis, not just concatenation.
## When to Use the Subagent Pattern
The subagent approach shines whenever a task involves several distinct types of work that can proceed independently before being combined. This includes scenarios like:
– Research tasks requiring multiple angles (technical, financial, and user-experience perspectives).
– Code review where different aspects—security, performance, readability—need separate scrutiny.
– Content creation involving research, drafting, and editing handled by different specialists.
– Any multi-step project where parallelism saves time and domain expertise improves quality.
There are multiple ways to activate this pattern. For one-off tasks, you can simply mention subagents directly in your prompt, as we did above. For recurring workflows across an entire project, you can encode the strategy in an `AGENTS.md` file so that Codex automatically follows this approach. If you want to package the workflow as a reusable template, you can define it in a `SKILL.md` file, which allows Codex to invoke subagents whenever that skill is triggered.
It is helpful to keep this distinction in mind: the agent definition files in `.codex/agents/` determine **who** the subagents are—their identity, specialization, and instructions. Meanwhile, prompts, `AGENTS.md`, and skills determine **when and how** those subagents get invoked. Keeping these layers separate gives you flexibility and reusability.
## Frequently Asked Questions
### What exactly is a subagent in Codex?
A subagent is a separate, focused instance of an AI agent that Codex spawns to handle one specific aspect of a larger task. Each subagent runs in its own isolated thread with its own context and tool access, and reports back to the main agent for final aggregation.
### Do subagents cost more than a single-agent workflow?
Since subagents are effectively separate LLM calls running in parallel, the total compute usage can be higher than a single monolithic pass. However, the tradeoff is often worth it: you get faster results, deeper domain coverage, and more nuanced analysis that a single pass might miss.
### Can I customize which model each subagent uses?
Yes. In the agent’s TOML definition, you can override the model, reasoning effort, and other settings on a per-agent basis. If you don’t specify anything, the subagent inherits the configuration from the main session.
### How do I inspect what each subagent is doing?
You can use the agent-thread view accessible from the CLI. This lets you see each subagent’s individual context, tool calls, and intermediate results in real time while they are working.
### Can subagents use web search?
Web search only needs to be enabled for the main session. When Codex spawns subagents, they automatically inherit this capability, so each specialist can look up information independently.
### What file formats do I need for subagent setup?
Subagents are defined as TOML files placed in the `.codex/agents/` directory. Project-level concurrency and configuration settings go in `.codex/config.toml`. Optional strategies can be documented in `AGENTS.md` or packaged as reusable skills in `SKILL.md`.
### Is there a limit on how many subagents I can run?
You control this yourself through the `max_concurrent_threads_per_session` setting in your project configuration. You can set it to any number that fits your needs and resource constraints.
## Conclusion
The subagent pattern represents a significant leap forward in how AI assistants handle complex, multi-dimensional tasks. By giving Codex the ability to spawn specialized agents that work in parallel, you unlock faster execution, deeper expertise, and more thoughtful synthesis of results. Whether you are planning a trip, reviewing code, or researching a multifaceted problem, defining and delegating to subagents transforms a single AI interaction into a coordinated team effort.
Start small—try adding one or two specialist agents to a project and see how they change the quality of your outputs. As you get comfortable, you can build more sophisticated workflows using `AGENTS.md` and `SKILL.md` to make subagent delegation a seamless part of your everyday coding and problem-solving process.
Thank you for reading
