> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Subagents Multi Agent Systems and Orchestrators
> Explains orchestrators and subagents for decomposing tasks to scale multiagent systems beyond single-agent context limits.
An agent can be represented as a single unit: one model, its harness, and a single internal loop running inside a fixed-size context window. For many focused tasks — for example, "book a flight under \$300" — a single-loop agent is sufficient. But some problems exceed what one loop and one context window can reliably handle. In those cases the agent hits limits: the context window fills, history drops out, and the agent loses the thread of the work.
This document explains how to scale beyond a single loop using subagents and orchestration.
## The single-agent limit
Consider packaging everything — the model, the harness, and its loop — into one agent unit and giving it a large goal such as:
* "Research 12 vendors, compare them, and write a recommendation."
All vendor data, comparisons, drafts, and loop history must fit inside the same limited context. One LLM cannot hold all of that reliably at once. The likely failure modes are:
* Context truncation (important history removed)
* Loss of coherence across steps
* Degraded or incorrect final output
When a single loop isn't enough, scaling up by enlarging the context or making one monolithic agent is not the optimal approach.
## The orchestration solution
Instead of having one agent try to do everything, make the top-level agent an orchestrator. The orchestrator’s job is to:
1. Decompose the large goal into smaller, well-defined subtasks.
2. Dispatch those subtasks to other agents (subagents).
3. Collect, validate, and stitch subagent results back into the final output.
In other words, the orchestrator acts as the lead coordinator; the workers are subagents.
Example partition for the vendor-research task:
* A research subagent that gathers vendor facts.
* A comparison subagent that evaluates and scores vendors.
* A writing subagent that drafts the recommendation.
Important: subagents are not new primitives. Each subagent is the same building block as the orchestrator — a model + harness + loop packaged as an agent instance. You instantiate multiple agents and assign them narrower jobs. Subagents can themselves act as orchestrators, spawning further subagents (for example, the research subagent can create 12 per-vendor subagents). This recursive capability is how complex, hierarchical workflows scale.
A subagent behaves, from the orchestrator's perspective, like a tool call: the orchestrator requests a result, waits for it, and receives the response. The orchestrator does not need to know the subagent's internal model, tools, or loop — it only needs the output.
## Key characteristics and design principles
* Reuse one building block: The entire system is the same agent design repeated at multiple levels. You do not invent new primitives — you reuse the agent pattern.
* Subagents as tools: To the orchestrator, subagents are abstractions that return results, analogous to calling a web API or a local tool.
* Recursive orchestration: Subagents may orchestrate further subagents, enabling hierarchical or distributed processing.
* Flexible orchestrators: The orchestrator can be an AI agent, or it can be plain code using a static plan. Use whatever fits your reliability and control needs.
* Multiple topologies: The architecture can be hierarchical, chain-based, peer-to-peer, or a hybrid. Agents can fan-out, pass work sideways, or collaborate in complex graphs.
## Quick reference table
| Component | Primary role | Example responsibility |
| - | - | - |
| Orchestrator (top-level agent) | Decomposes tasks, assigns subagents, recombines outputs | Split “research 12 vendors” into subtasks and merge results |
| Subagent | Executes a focused subtask inside its own loop & context | Run vendor-specific fact-finding or scoring |
| Worker-of-a-worker (recursive subagent) | Handles very fine-grained work created by a subagent | Scrape one vendor, normalize fields, return structured data |
## Example workflow (step-by-step)
1. Orchestrator receives goal: “Research 12 vendors, compare them, write recommendation.”
2. Orchestrator decomposes goal:
* Create a “vendor-research” task per vendor
* Create a “compare” task to aggregate results
* Create a “draft” task to produce the final recommendation
3. Orchestrator spawns subagents (or calls an orchestration API) and supplies each subagent with its task specification and data schema expectations.
4. Each subagent runs independently within its own context window and returns structured results.
5. Orchestrator validates or normalizes results, runs the comparison logic, and asks the writing subagent to draft the recommendation.
6. Orchestrator produces the final consolidated output and returns it to the user.
## When to use subagents
* The task requires memory beyond a single context window (long-running research, large datasets).
* You need robustness and modularity (isolated failures only affect one subtask).
* You want parallelism (multiple subagents operate concurrently).
* You need specialized processing (different subagents can use different tools, prompts, or models).
## Benefits and trade-offs
Benefits:
* Scalability through horizontal decomposition (scale out, not up).
* Improved fault isolation and recoverability.
* Easier reuse and specialization of subagents.
Trade-offs:
* Additional orchestration complexity (task splitting, result merging, retries).
* Potential latency from inter-agent calls and coordination.
* Need for well-defined interfaces and schemas between agents.
## Final recommendation
When a single loop feels too small for the job, prefer scaling out with subagents and orchestration rather than building a single, larger agent. Break the problem into clear subtasks, assign subagents to each, and have an orchestrator recombine verified results. This pattern—reusable agents coordinated by a lead—enables robust, maintainable, and scalable multi-agent systems.
Next time you face a task that exceeds a single context window, decompose the job, assign subagents, and orchestrate their results into one coherent answer.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.