Supervisor Pattern
The supervisor pattern coordinates specialized worker agents by calling them as tools. Learn when it earns its cost, how to build it with LangChain 1.0's current API, and how to evaluate whether it actually outperforms a single agent.
Quick Reference
- →The supervisor pattern = main agent + subagents wrapped as @tool functions (LangChain calls this 'subagents architecture')
- →Build with create_agent from langchain.agents — the langgraph-supervisor library and create_supervisor() are deprecated
- →Subagents are stateless: each @tool call gets a fresh context window; the supervisor maintains all conversation memory
- →Tool descriptions are the routing mechanism — the supervisor selects subagents based on tool names and descriptions
- →Two tool patterns: tool-per-agent (fine-grained control) or single dispatch tool with registry (scales to 5+ agents)
- →Set recursion_limit in every invoke config — a 3-worker supervisor uses ~2 LangGraph steps per routing round
- →Cost grows linearly with rounds: each supervisor call re-reads the full conversation history
- →For >5 workers, nest mid-level supervisors as tools for a top-level supervisor (hierarchical pattern)
Should I Use the Supervisor Pattern?
A central main agent coordinates specialized worker agents by calling them as tools. LangChain's documentation calls this the 'subagents architecture.' The supervisor reads the task, picks a worker via tool call, receives the result, and decides whether to route to another worker or finish.
A supervisor requires at minimum N+1 LLM calls for an N-worker workflow. Each additional routing round re-reads growing conversation history. The pattern earns its keep only when your evaluation set shows routing or tool-selection failures that a single agent with a focused prompt cannot fix. Start single-agent; add the supervisor when you have evidence you need it.
The sibling article 'Multi-Agent Systems' covers when to go multi-agent at all. This article focuses on when the supervisor pattern specifically beats the alternatives.
| Comparison | Use supervisor when | Use the alternative when |
|---|---|---|
| vs. single agent | The task genuinely requires 3+ distinct tool sets that can't coexist in one prompt without degrading selection accuracy | A single agent with domain-focused tools and a good prompt gets the job done — add a supervisor only after measuring that it doesn't |
| vs. router pattern | Tasks require multiple sequential worker invocations (research → write → review), not a single dispatch | Every task maps to exactly one specialist — use the router pattern, which has one fewer LLM call |
| vs. swarm/handoffs | You need centralized control, a full audit trail of routing decisions, and the ability to re-route after each worker | Workers naturally hand off to each other in a predictable sequence and don't need a central coordinator |
| vs. orchestrator-worker | Tasks are dynamic — the supervisor decides routing reactively based on prior results, not from a fixed upfront plan | The workflow is fixed or plan-shaped: generate a plan, execute steps in parallel, aggregate — use orchestrator-worker |
Supervisor routes tasks to workers and loops until the goal is met
Each worker you add increases the supervisor's routing surface. Two workers is the minimum viable supervisor. Add a third only after measuring on your eval set that it improves end-to-end quality — not because it feels more complete.