From One Agent to a Workforce: Understanding Codex Subagents

After we ask Codex to finish a job, we normally consider it as a single agent.

But when some duties are advanced sufficient and contain a number of distinct forms of work, Codex will attempt to divide the issue into smaller duties and spawn separate brokers to work on them.

These delegated brokers are referred to as subagents.

Every subagent works in its personal thread and focuses on just one a part of the unique job. On the identical time, the primary agent coordinates their work and produces the ultimate response by aggregating the subagents’ outcomes.

As practitioners, this naturally results in this query:

How can we use subagents intentionally for our personal issues?

On this submit, we’ll discover Codex subagents via a hands-on case research. Alongside the way in which, we’ll see find out how to outline and delegate work to specialist brokers, examine their particular person threads, and let the primary agent mix their findings right into a last consequence.

···

1. Case Examine: Planning a Journey with Specialist Brokers

Right here, we think about a journey planning job.

Suppose we wish to plan a four-day solo journey from Zurich. We have now a complete funds of 1,200 Swiss Francs. Our potential locations embody Lisbon, Prague, and Copenhagen, and we care about handy journey, museums, and native meals.

For this job, we put together three specialist brokers:

• Journey logistics agent

• Finances analyst

• Expertise researcher

Every specialist will consider all three locations from its personal perspective. The primary agent will then gather their findings, examine the tradeoffs, and suggest one last vacation spot.

1.1 Defining the Specialist Brokers

We begin by defining our specialist brokers.

Codex permits us to outline customized brokers for a particular challenge. We are able to do that by including TOML recordsdata underneath .codex/brokers/:

.codex/├── config.toml└── brokers/    ├── travel-logistics.toml    ├── budget-analyst.toml    └── experience-researcher.toml

Every agent definition requires three fields:

• identify: how Codex identifies the agent.

• description: what this agent is.

• developer_instructions: how the agent ought to behave.

Right here is the definition for the journey logistics agent:

identify = "travel_logistics"description = "Journey specialist for evaluating routes and journey comfort throughout candidate locations."developer_instructions = """Consider each vacation spot from a travel-logistics perspective.Return concise, source-backed findings to the primary agent."""

For the funds analyst:

identify = "budget_analyst"description = "Finances specialist for evaluating the probably journey price throughout candidate locations."developer_instructions = """Consider each vacation spot from a trip-budget perspective.Return concise, source-backed findings to the primary agent."""

And the expertise researcher:

identify = "experience_researcher"description = "Vacation spot specialist for evaluating how nicely every choice matches the traveler's acknowledged pursuits."developer_instructions = """Consider each vacation spot in opposition to the traveler's acknowledged pursuits.Return concise, source-backed findings to the primary agent."""

A customized agent may also specify its personal mannequin, reasoning effort, sandbox configuration, instruments, and abilities. If we don’t override these settings right here, the three specialists will inherit them from the primary Codex session.

Moreover, we add a small project-level configuration in .codex/config.toml:

[agents]max_concurrent_threads_per_session = 3

This permits as much as three subagent threads to run concurrently.

1.2 Operating the Subagent Workflow

Now that the three specialists can be found, we can provide the primary agent our particular job:

I'm planning a four-day solo leisure journey from Zurich from October 15 toOctober 18, 2026. My whole funds is CHF 1,200.Examine Lisbon, Prague, and Copenhagen. I care about handy journey,museums, and native meals.Use the `travel_logistics`, `budget_analyst`, and `experience_researcher`brokers in parallel. Every agent ought to consider all three locations from itsspecialty. Watch for all three brokers, then suggest one vacation spot andclarify the primary tradeoffs with supply hyperlinks.

Within the immediate, we explicitly requested the primary agent to make use of our outlined specialist brokers when fixing the duty.

To run the case research, we will begin Codex from the challenge listing with net search enabled:

Notice that we solely must allow net seek for the primary session. The three subagents inherit this functionality when Codex spawns them.

Then, we will submit the immediate:

We see that Codex began the three specialist brokers in parallel:

We are able to examine their progress instantly from the CLI utilizing:

This opens the agent-thread view, as every specialist has its personal context, software exercise, and eventual consequence:

As soon as all three brokers end, their findings are returned to the primary agent for synthesis.

1.3 Inspecting the Outcomes

Now we will test what they produced.

I can see that every subagent returned a advice from its personal perspective. Very fascinating, they didn’t arrive on the identical conclusion: the journey logistics subagent suggests Copenhagen, the funds subagent recommends Prague, whereas the expertise subagent says Lisbon is the only option.

The primary agent collected particular person responses and really useful Lisbon as the most effective steadiness throughout journey comfort, price, museums, and native meals.

So, we will see that the primary agent certainly in contrast the subagents’ findings in opposition to the unique necessities and made an total judgment, as a substitute of merely repeating one reply or concatenating three experiences.

···

2. When the Subagent Sample Is Helpful

The subagent sample is beneficial when a job accommodates a number of several types of work that may be accomplished independently after which mixed. A essential agent is orchestrating the workflow, and as soon as particular person subagents have accomplished their duties, it might probably mix their findings and produce the ultimate reply.

In our case research, we requested the three subagents instantly within the immediate. That is the only strategy for a one-off job, however it’s after all not the one strategy to invoke the sample.

We are able to additionally specify this sample in a devoted AGENTS.md, if we would like Codex to observe this technique all through a challenge. Moreover, if the workflow addresses a recurrent job, we will package deal the directions in a SKILL.md. Codex can then observe the ability instruction and delegate subagents accordingly.

Simply have in mind: the agent recordsdata (i.e., .codex/brokers/*.tom) nonetheless outline who the subagents are, whereas the immediate, AGENTS.md, or abilities outline when and the way they need to be used.