Docs · Sub-agents
Sub-agents and orchestration
Updated September 25, 2026 · by Nishanthan Janarthanarajah (Nishy), founder of Agent Studio
Why split an agent into specialists
- Focused prompts behave better than one giant prompt that tries to do everything.
- You can give each specialist the right model: a strong one for reasoning, a fast one for lookups and formatting.
- Traces become readable: you see which specialist did what, with its task and result.
- Limits and policies can differ per specialist without touching the orchestrator.
Setting one up
| Field | What to write |
|---|---|
| Name | A short role: Order Tracker, Refund Desk, Research. |
| What this sub-agent does | One or two sentences the orchestrator uses to decide when to delegate. Be concrete about inputs. |
| System prompt | Instructions for the specialist: its narrow job, the inputs it expects, the format and length of what it returns, and what to do when a task is out of scope. |
| Model | Often a faster model than the orchestrator. |
Then drag a connection from the orchestrator's bottom handle to the sub-agent's top handle. Unconnected sub-agents are ignored at deploy time and flagged as a warning.
What happens at runtime
The orchestrator's instructions gain a roster of its team with each description. When it decides to delegate, it calls the specialist's tool with a task string. The specialist runs its own short loop and returns text. The orchestrator can call several specialists in one request, then writes the final reply. Output guardrails check that reply before it leaves.
See the API reference for the delegate entries in the trace, and how it works for the full pipeline.
Frequently asked questions
What is a sub-agent?+
A specialist with its own model and system prompt. When you connect it to the orchestrator on the canvas, it becomes a tool the orchestrator can call with a task; it runs independently and returns a result.
How does the orchestrator know when to delegate?+
From the sub-agent's description. Write it like a job title plus a sentence, for example 'Looks up order status and shipping details for a given order number'. The orchestrator sees all descriptions and chooses.
Can sub-agents call other sub-agents?+
Not in the current version. The orchestrator delegates; sub-agents complete a task and return. This keeps runs predictable and traces readable.
Can I use a cheaper model for a sub-agent?+
Yes, and you usually should. Many teams run the orchestrator on GPT-OSS 120B and specialists on GPT-OSS 20B or Llama 3.1 8B.
How many sub-agents can I add?+
Starter allows 1 per agent, Pro 2, Growth 3, and Agency 20.