BuildPython

Orchestration Patterns: Supervisor, Swarm, Hierarchical

Four orchestration patterns recur across 2026 frameworks: supervisor-worker, swarm / peer-to-peer, hierarchical, and debate. Anthropic's guidance applies to all of them: "It's about building the right system for your needs." Start simple, and add topology only when a single agent plus five workflow patterns falls short.

TIME: ~60 minutesPREREQUISITES: Phase 14 · 12 (Workflow Patterns), Phase 14 · 25 (Multi-Agent Debate)

Learning Objectives

Name the four recurring orchestration patterns and when each fits.
Describe the 2026 LangChain recommendation: tool-call-based supervision vs supervisor libraries.
Explain Anthropic's "build the right system" rule and how it gates topology choice.
Implement all four in stdlib against a common scripted LLM.

The Problem

Teams reach for "multi-agent" before they need it. An orchestration pattern is the shape of the routing between agents: who decides what runs next, and who is allowed to hand work to whom. Four of them recur across frameworks. Once you can name them, you can pick the one that fits or skip topology entirely.

Warm-up0/3

1. In Anthropic's workflow-patterns framing, how does a workflow differ from an agent?Warm-up

2. In multi-agent debate, what does each model instance do first?Warm-up

3. Which of Anthropic's workflow patterns has a central LLM break a task into subtasks and delegate them to workers?Warm-up

The Concept

Supervisor-worker

Supervisor-worker is a topology where a central routing LLM dispatches work to specialist agents. On each turn the supervisor decides whether to loop back to itself, hand off to a specialist, or terminate. Specialists never talk to each other. Every route goes through the supervisor.

Frameworks: LangGraph create_supervisor, Anthropic orchestrator-workers, CrewAI Hierarchical Process.

2026 LangChain recommendation: do supervision through direct tool calls rather than create_supervisor. You get finer control over context engineering, because you decide exactly what each specialist sees.

Swarm / peer-to-peer

A swarm is a topology where agents hand off directly to one another through a shared tool surface, with no central router. Fewer hops means lower latency than a supervisor. The price is that nothing owns control, so the system is harder to reason about.

Frameworks: LangGraph swarm topology, OpenAI Agents SDK handoffs (when all agents can hand off to all others).

Hierarchical

Hierarchical orchestration stacks supervisors: supervisors manage sub-supervisors, which manage workers. LangGraph implements it as nested subgraphs and CrewAI as nested crews. It scales to large agent populations at the cost of operational complexity.

You need it when a single supervisor's context budget cannot hold descriptions of all its specialists.

Debate

Debate runs parallel proposers and iterative cross-critique (Lesson 25). It is closer to verification than orchestration, but frameworks expose it as a topology choice, so it belongs on the list.

CrewAI Crew vs Flow

CrewAI formalizes two deployment modes:

Flow is for deterministic, event-driven automation, and the recommended starting point for production.
Crew is for autonomous, role-based collaboration.

This is orthogonal to the four patterns above, but it maps onto topology: Flow is typically supervisor or hierarchical, and Crew is typically a supervisor with an LLM router.

Anthropic's guidance

"Success in the LLM space isn't about building the most sophisticated system. It's about building the right system for your needs."

Decision order:

Single agent + workflow patterns (Lesson 12). Start here.
Supervisor-worker, when you have 2-4 specialists.
Swarm, when latency matters more than reasoning clarity.
Hierarchical, only when the supervisor's context budget fails.
Debate, when accuracy matters more than cost.

Where this pattern goes wrong

Topology-first thinking. "We need multi-agent" before anyone has identified what problem multi-agent solves.
Bouncing handoffs in swarm. A -> B -> A -> B. Use hop counters.
Fake hierarchy. Three layers because "enterprise," but only two actual teams. Collapse it.

Check: The Concept0/23

1. What is a supervisor-worker topology?Define

2. What is a swarm topology?Define

3. What is hierarchical orchestration?Define

4. What is the debate pattern?Define

5. What does tool-call-based supervision mean?Define

6. In CrewAI, what is a Crew?Define

7. In CrewAI, what is a Flow?Define

8. Why does the 2026 LangChain recommendation prefer direct tool calls over a supervisor library such as create_supervisor?Explain

9. What is the trade-off of a swarm compared with a supervisor-worker setup?Explain

10. When is hierarchical orchestration justified?Explain

11. How does the lesson characterize debate relative to the other three patterns?Explain

12. What decision order does the lesson recommend?Explain

13. At what specialist count does the decision order make supervisor-worker the right choice?Explain

14. Per the decision order, which condition points toward a swarm?Explain

15. What is topology-first thinking, per the lesson's pitfalls?Explain

16. How do you stop bouncing handoffs in a swarm (A -> B -> A -> B)?Explain

17. What does the lesson mean by fake hierarchy?Explain

18. A company has two real teams, billing and support. Its system has three supervisor layers, and the top layer only forwards each request to the layer below it. What is the diagnosis?Analyze

19. A team built on create_supervisor cannot control which messages each specialist receives, and answers degrade as the shared context grows. Which change does the 2026 recommendation point to?Analyze

20. Your support bot uses one router and 3 specialists. It grows to 15 specialists and the router prompt can no longer hold all their descriptions. What does the decision order suggest?Design

21. Your single agent with workflow patterns handles customer tickets well, but a colleague proposes a three-agent supervisor setup to look modern. What should you do?Design

22. You have three specialists and a strict latency budget, and you can accept a system that is harder to trace. Which design fits?Design

23. You must ship a production ticket automation that reacts to events and has to behave predictably. Which CrewAI mode do you start from?Design

Build It

code/main.py implements all four patterns in stdlib against a scripted LLM:

Supervisor: central router.
Swarm: peer-to-peer with direct handoffs.
Hierarchical: supervisors of supervisors.
Debate: parallel proposers plus critique.

Each pattern handles the same three-intent task (refund / bug / sales), so the traces differ in shape.

Run it:

python3 code/main.py

The output is a per-pattern trace and an op count. Supervisor is cleanest, swarm is shortest, hierarchical is deepest, and debate is most expensive.

Check: Build It0/7

1. In main.py's swarm(), how is the task "the CLI crashes on ctrl-c" handled?Apply

2. How many ops does supervisor_worker() report for the three tasks in main.py?Apply

3. In hierarchical(), which group receives "the CLI crashes on ctrl-c" and how many ops does that task cost?Apply

4. How many ops does debate() report for the three tasks in main.py?Apply

5. Why does the swarm report 5 ops where supervisor_worker reports 6 on the same three tasks?Apply

6. Two agents in a swarm keep passing one ticket back and forth. In main.py's swarm(), which piece is there to stop that?Analyze

7. A team routes refund, bug and sales tickets with a three-proposer debate and finds it costs 2.5 times the supervisor version (15 ops against 6) for the same labels. What went wrong?Analyze

Use It

LangGraph for supervisor and hierarchical (nested subgraphs).
OpenAI Agents SDK for handoffs-as-tools (supervisor-shaped when one triage agent owns the routing, swarm-shaped when every agent can hand off to every other).
CrewAI Flow for deterministic production work.
Custom for debate, or when you want exact control.

Check: Use It0/1

1. When is an OpenAI Agents SDK handoff setup swarm-shaped rather than supervisor-shaped?Explain

Ship It

outputs/skill-orchestration-picker.md is a skill that picks a topology and implements it.

Author's Note

I treat "we need multi-agent" as a symptom, not a requirement. My bet is that a topology should have to name the problem it solves before it gets added, and the decision order in this lesson is that rule written down: a single agent plus workflow patterns first, then supervisor-worker for 2-4 specialists, and hierarchical only when the supervisor's context budget fails. If I can't point at the failure a layer fixes, I leave it out. That's also how I read "fake hierarchy": three layers wrapped around two actual teams is topology added to look serious, and I'd collapse it. When I do need a supervisor, I'd start with direct tool calls instead of a supervisor library, so I decide exactly what each specialist sees.

Exercises

Convert a supervisor-worker to a swarm by removing the router. What breaks? What improves?
Add a hop counter to the swarm: refuse after 3 handoffs. Does it catch A->B->A bouncing?
Build a two-level hierarchical system for a 12-specialist domain. Where does the context budget fail without nesting?
Profile the four patterns on a production-shaped workload. Which wins on which metric (latency, cost, accuracy, debuggability)?
Read Anthropic's "Building Effective Agents" post. Map each of your production flows to one of the four. Any that don't map cleanly?

Key Terms

Term	What people say	What it actually means
Supervisor-worker	"Router + specialists"	Central LLM dispatches to specialists; they don't talk to each other
Swarm	"Peer-to-peer"	Direct handoffs via shared tools; no central router
Hierarchical	"Supervisors of supervisors"	Nested subgraphs for large populations
Debate	"Proposer + critique"	Parallel proposers, cross-critique (Lesson 25)
Tool-call-based supervision	"Supervisor without a library"	Implement supervisor as direct tool calls for context control
Crew	"Autonomous team"	CrewAI's role-based collaboration mode
Flow	"Deterministic workflow"	CrewAI's event-driven production mode