From One Agent to a Team: Understanding Codex Subagents

When we ask Codex to complete a task, we usually think of it as a single agent.But if some tasks are complex enough and involve several distinct types of work, Codex will try to divide the problem into smaller tasks and spawn separate agents to work on them.These delegated agents are called subagents.Each subagent works in its own thread and focuses on only one part of the original task. At the same time, the main agent coordinates their work and produces the final response by aggregating the subagents' results.As practitioners, this naturally leads to this question:How can we use subagents deliberately for our own problems?In this post, we’ll explore Codex subagents through a hands-on case study. Along the way, we’ll see how to define and delegate work to specialist agents, inspect their individual threads, and let the main agent combine their findings into a final result.···1. Case Study: Planning a Trip with Specialist AgentsHere, we consider a travel planning task.Suppose we want to plan a four-day solo trip from Zurich. We have a total budget of 1,200 Swiss Francs. Our potential destinations include Lisbon, Prague, and Copenhagen, and we care about convenient travel, museums, and local food.For this task, we prepare three specialist agents:Travel logistics agentBudget analystExperience researcherEach specialist will evaluate all three destinations from its own perspective. The main agent will then collect their findings, compare the tradeoffs, and recommend one final destination.1.1 Defining the Specialist AgentsWe start by defining our specialist agents.Codex allows us to define custom agents for a specific project. We can do this by adding TOML files under .codex/agents/:Each agent definition requires three fields:name: how Codex identifies the agent.description: what this agent is.developer_instructions: how the agent should behave.Here is the definition for the travel logistics agent:For the budget analyst:And the experience researcher:A custom agent can also specify its own model, reasoning effort, sandbox configuration, tools, and skills. If we do not override those settings here, the three specialists will inherit them from the main Codex session.Additionally, we add a small project-level configuration in .codex/config.toml:This allows up to three subagent threads to run concurrently.1.2 Running the Subagent WorkflowNow that the three specialists are available, we can give the main agent our specific task:In the prompt, we explicitly asked the main agent to use our defined specialist agents when solving the task.To run the case study, we can start Codex from the project directory with web search enabled:Note that we only need to enable web search for the main session. The three subagents inherit this capability when Codex spawns them.Then, we can submit the prompt:Figure 1. Launch Codex and submit the prompt. (Image by author)We see that Codex started the three specialist agents in parallel:Figure 2. Codex spawned three specialist agents. (Image by author)We can inspect their progress directly from the CLI using:This opens the agent-thread view, as each specialist has its own context, tool activity, and eventual result:Figure 3. We can inspect individual agents' activities. (Image by author)Once all three agents finish, their findings are returned to the main agent for synthesis.Figure 4. Main agent supervises the whole process. (Image by author)1.3 Inspecting the ResultsNow we can check what they produced.I can see that each subagent returned a recommendation from its own perspective. Very interesting, they did not arrive at the same conclusion: the travel logistics subagent suggests Copenhagen, the budget subagent recommends Prague, while the experience subagent says Lisbon is the best choice.The main agent collected individual responses and recommended Lisbon as the best balance across travel convenience, cost, museums, and local food.So, we can see that the main agent indeed compared the subagents' findings against the original requirements and made an overall judgment, instead of simply repeating one answer or concatenating three reports.···2. When the Subagent Pattern Is UsefulThe subagent pattern is useful when a task contains several different types of work that can be completed independently and then combined. A main agent is orchestrating the workflow, and once individual subagents have completed their tasks, it can combine their findings and produce the final answer.In our case study, we requested the three subagents directly in the prompt. This is the simplest approach for a one-off task, but it is of course not the only way to invoke the pattern.We can also specify this pattern in a dedicated AGENTS.md, if we want Codex to follow this strategy throughout a project. Additionally, if the workflow addresses a recurrent task, we can package the instructions in a SKILL.md. Codex can then follow the skill instruction and delegate subagents accordingly.Just keep in mind: the agent files (i.e., .codex/agents/*.tom) still define who the subagents are, while the prompt, AGENTS.md, or skills define when and how they should be used.