Sub-Agents Pattern

The mental model: HR planning a birthday

Imagine you're HR at a company, and the boss says: "It's Suzy's birthday, make sure you organize something special." You spring into action. You need a cake, so you call a baker. You need the staff room decorated, so you call a decorator. You want food, so you call a caterer.

You coordinate all of it, you check in on the baker's progress, negotiate with the decorator, tell the caterer the headcount, and make sure nothing conflicts (the decorator shouldn't be arranging the yard when the party's in the staff room). None of these specialists talk to the CEO directly, they report to you, and you report a single, synthesized status back up: "cake's arriving at social time, room's ready, food's delivered."

That's the sub-agents pattern: a central coordinator delegates to specialized sub-agents, synchronizes their work, and is the only one who talks to the user.

Mapped onto the pattern: HR is the coordinator, the baker is sub-agent 1, the decorator is sub-agent 2, and the caterer is sub-agent 3.

Characteristics of the sub-agents pattern

1. Centralized control - one main agent makes every routing and delegation decision. The baker, decorator, and caterer don't decide who gets called next, HR does.
2. Sub-agents are implemented as tools - each sub-agent is built (e.g., with create_agent), wrapped in a tool function that invokes it and returns its response, and that tool is handed to the coordinator.
3. No direct user interaction - sub-agents never talk to the user. Just like the baker and caterer never call the CEO directly, only the coordinator has that channel.
4. Context isolation - each sub-agent runs in a fresh, stateless context with no memory of past calls. If the CEO asks "what cake did we order?", HR answers from her own memory, the baker doesn't remember.
5. Result synthesis - the coordinator is responsible for combining every sub-agent's output into one coherent response for the user.

Why context isolation matters

It might seem limiting that sub-agents can't remember anything between calls, but that's deliberate:

• Prevents context bloat - the coordinator is trusted to hand each sub-agent exactly the context it needs, instead of every sub-agent accumulating irrelevant history over time.
• Keeps sub-agents focused - a sub-agent stuffed with stale or unrelated context makes worse decisions. A clean context per call means it only ever reasons about the task in front of it.
• Pushes complexity to one place - the coordinator does the heavy lifting of remembering and re-injecting context, so sub-agents can stay simple and single-purpose.

Process flow

1. Request received - the user sends a query to the main agent.
2. Routing decision - the main agent analyzes the request and decides which sub-agents to call. Not every sub-agent gets called every time, a birthday in 15 minutes might only need the baker, skipping the caterer entirely.
3. Delegation - the chosen sub-agents (invoked as tools) execute their tasks and return results. Each one is a one-and-done call; their context is cleared immediately after.
4. Synthesis - the main agent combines the results into a final response and (if using a checkpointer) retains the conversation memory for follow-up questions. The sub-agents never retain anything.

Design decisions

When building this pattern from scratch (with create_agent/react_agent, many of these are handled for you), you'll need to decide:

• Sync vs. async execution - should the coordinator wait for one sub-agent to finish before calling the next? Use synchronous calls when a sub-agent's output feeds the next one's input (e.g., the decorator needs the cake's size before choosing a stand). Use asynchronous, parallel calls when tasks are independent and long-running (e.g., the baker and caterer working simultaneously).
• What each sub-agent receives - just the task/query, the query plus some relevant context, or the entire shared state. Since sub-agents are stateless, anything they need has to be explicitly passed in by the coordinator; passing full state is possible but usually creates unnecessary tight coupling.
• What the main agent sends back to the user - just the final answer, the answer plus the reasoning behind it (useful when the user needs to validate why), or the full message history from every sub-agent (useful for debugging or when embedding this system inside another one that needs full transparency).

Benefits vs. trade-offs

Benefits:

• Clear separation of concerns - each sub-agent owns one domain and does it well, with no context bleeding between agents.
• Centralized orchestration - one place controls all workflow decisions, so debugging routing or sequencing issues means looking in exactly one place.
• Context isolation - reinforced from above: focused, uncluttered context per sub-agent.
• Parallel execution (optional) - independent sub-agents can be invoked simultaneously without a latency penalty.
• Independent development - different developers or teams can own different sub-agents without stepping on each other.
• Easier testing - sub-agents can be unit-tested in isolation, then integration-tested together.
• Scalability - new sub-agents can be added, or existing ones improved or removed, without disrupting the rest of the system.
• Better tool selection - each sub-agent gets only the tools relevant to its domain, so it makes sharper decisions.
• Modular maintenance - updating one sub-agent's prompt or tools doesn't require touching the others.

Trade-offs:

• Extra LLM calls - the coordinator makes a call to decide who to invoke, the sub-agent makes its own call(s) to do the work, and the coordinator makes another call to synthesize the result. That's overhead on top of a single-agent flow, and there's no way around it, just budget for it.
• No direct user interaction - sub-agents can't ask the user for clarification. Mitigate with human-in-the-loop interrupts, or by having the coordinator gather all necessary details from the user before delegating.
• Statelessness - sub-agents can't remember previous calls; the coordinator must pass all necessary context every time.
• Increased latency - all the back-and-forth adds up. Parallelism helps where tasks are independent, but the sequential back-and-forth for dependent tasks can't be avoided.
• Higher cost - more tokens processed across more calls; the cost is worth it for the orchestration you get, but it's real.
• Synthesis complexity - the coordinator needs strong prompting to combine sub-agent outputs coherently, especially when their outputs could conflict.
• Routing errors - ambiguous tool descriptions or vague sub-agent prompts can cause the coordinator to call the wrong sub-agent (or skip one it should have called). Clear boundaries and precise tool descriptions are the fix.

When to use this pattern

• The work splits into distinct specialist domains that aren't dependent on each other's internals.
• Sub-agents don't need to talk to the user directly.
• You want centralized control and a single point of accountability for routing decisions.
• You need context isolation between specialists.
• Parallel execution is useful but optional, unlike the router pattern (covered next), parallelism here is a choice, not a requirement.
• Different teams should own different agents, or you want a clean separation for testing and maintenance.

Common use cases

• Personal assistants - a calendar agent, an email agent, a task agent, all coordinated by one conversational front-end. (This is close to how a ChatGPT-style assistant delegates to specialized tools under the hood.)
• Research workflows - a researcher sub-agent, an analyst sub-agent, and a writer sub-agent, run sequentially or in parallel.
• Customer data platforms - a CRM agent, an analytics agent, a reporting agent, each specialized on one slice of customer data.
• Code generation - a planning agent, a code-writing agent, and a review agent, chained together.
• Content creation - a research agent, an outline agent, and a writing/editing agent.

The sub-agents pattern is flexible enough to run sequentially, in parallel, or a mix of both, which is exactly why it's usually the first pattern reached for when a single agent starts feeling overloaded.