Orchestration Patterns

In plain words

Think of a college fest. One coordinator forwarding work to teams is a supervisor setup. Volunteers messaging each other directly with no coordinator is a swarm. Coordinators above coordinators is a hierarchy. Everyone answering and then arguing is debate. Multiple agents need the same choice, and the honest answer is usually to start with one agent and add a shape only when you can name what it fixes.

How it flows

A tiny example

def supervisor(text):
    who = classify(text)      # refunds / bugs / sales
    return run_agent(who, text)

def swarm(text, current, hops=0):
    reply, nxt = run_agent(current, text)
    if reply:
        return reply
    if hops >= 3:             # stop endless bouncing
        return "refused"
    return swarm(text, nxt, hops + 1)

Notice the swarm needs a hop counter, because with no central router two agents can pass the same request to each other forever.

What you will learn

• The four ways people wire multiple agents together, and what each one is called.
• How to pick the simplest one that solves your problem.
• Why "let us make it multi-agent" is usually the wrong first move.
• How to write all four shapes yourself in plain Python.

The problem, simply

Think about your college fest organising team. There is one main coordinator. Below her, there is a food team, a stage team, a sponsorship team. Somebody asks "where is the mic?" and the coordinator forwards it to the stage team. Simple.

Now imagine forty volunteers messaging each other with no coordinator. Sometimes faster, because nobody is a bottleneck. Sometimes the same question bounces between two people for an hour.

Agents have exactly this problem. Once you have more than one agent, you must decide who talks to whom. That wiring is called the orchestration pattern, or the topology. An agent, here, just means an LLM that can call tools in a loop until a task is done.

See, the mistake most teams make is jumping straight to "we need a multi-agent system" before they know what the extra agents are for. A fest with three volunteers does not need three layers of coordinators.

Tip

Tip: Before you add a second agent, ask what exactly the first agent was failing at. If you cannot answer in one sentence, you do not need the second agent yet.

The idea

There are four shapes that keep showing up across every agent framework. Learn the names, because interviewers use them.

1. Supervisor-worker

One central agent, the supervisor, reads the request and decides who handles it. The specialists never talk to each other. Everything goes through the middle.

This is the fest coordinator. Easy to debug, because every decision happens in one place: you just read the supervisor's log.

Suppose Priya builds a support bot for a laptop store. Three specialists: refunds, bug reports, sales. A customer types "my order says delivered but nothing came." The supervisor reads it, sees this is a refund issue, and hands it to the refund specialist. The sales specialist never even sees the message.

One practical note. Most frameworks ship a ready-made supervisor helper. The current advice from the team behind LangGraph, a popular agent framework, is to skip it and let the supervisor call each specialist as a normal tool. Why? Because then you control exactly what text each specialist receives, and deciding that is most of the job.

2. Swarm, or peer-to-peer

No supervisor at all. Every agent can directly hand the conversation to any other agent. They share one set of handoff tools.

Fewer hops, so it is faster and cheaper. But nobody is in charge, so there is no single log to read.

The classic failure here is bouncing. The refund agent thinks it is a sales question, sales thinks it is a refund question, and they pass it back and forth forever while your bill climbs. The fix is boring and it works: keep a counter of handoffs and refuse after, say, three.

3. Hierarchical

Supervisors managing sub-supervisors managing workers. Fest coordinator, then team leads, then volunteers.

This is only worth it when one supervisor cannot hold the descriptions of all the specialists in its context window. Twelve specialists eating your whole prompt? Split them into three groups of four and put a mini-supervisor over each group.

IMPRemember: hierarchy is a cure for a context-size problem, not a sign of a serious system. Three layers when you have two real teams is just extra latency and extra places to break.

4. Debate

Several agents answer the same question independently, criticise each other, and you take the settled result. Strictly speaking this is a checking technique, not a wiring one, but frameworks offer it as a topology. See the Multi-Agent Debate lesson in Module 5 for the full version.

It costs the most, because you are paying three or four models to do one job. Use it when a wrong answer is expensive.

How to choose

Go down this list and stop at the first thing that works.

1. One agent with a plain workflow. Start here, always.
2. Supervisor-worker, once you have roughly two to four clear specialists.
3. Swarm, when speed matters more than being able to explain what happened.
4. Hierarchical, only when the supervisor's context genuinely will not fit.
5. Debate, when correctness is worth more than the extra cost.

Anthropic's public guidance on agents says it plainly: the goal is the right system for your need, not the most sophisticated one.

Warning

Warning: A topology is not free. Every extra agent is another prompt to maintain, another failure mode, and another thing to explain to the person debugging at 2 a.m.

Build it

This runs the same three-intent task through all four shapes, using a fake toy model so nothing calls the internet.

"""Four orchestration shapes over one toy 'model'. Standard library only."""

# A fake model: given text, guess which specialist should handle it.
def classify(text):
    t = text.lower()
    if "refund" in t or "money" in t:
        return "refunds"
    if "crash" in t or "error" in t:
        return "bugs"
    return "sales"

def specialist(name, text):
    """A worker agent. Returns (reply, handoff_target_or_None)."""
    correct = classify(text)
    if name != correct:
        return (None, correct)          # not mine -> hand off
    return ("%s team: handling '%s'" % (name, text), None)

def supervisor(text, trace):
    """Central router. Every hop passes through here."""
    target = classify(text)
    trace.append("supervisor -> " + target)
    reply, _ = specialist(target, text)
    trace.append(target + " -> supervisor")
    return reply

def swarm(text, trace, start="sales", max_hops=3):
    """No router. Agents hand off to each other, capped by a hop counter."""
    current, hops = start, 0
    while hops <= max_hops:
        trace.append("at " + current)
        reply, nxt = specialist(current, text)
        if reply:
            return reply
        trace.append(current + " -> " + nxt)
        current, hops = nxt, hops + 1
    return "refused: too many handoffs"

def hierarchical(text, trace):
    """Top supervisor picks a group, the group's mini-supervisor picks a worker."""
    groups = {"money": ["refunds"], "product": ["bugs", "sales"]}
    target = classify(text)
    group = "money" if target in groups["money"] else "product"
    trace.append("top -> " + group + " lead")
    trace.append(group + " lead -> " + target)
    return specialist(target, text)[0]

def debate(text, trace, rounds=3):
    """Several proposers answer; majority vote wins."""
    votes = [classify(text) for _ in range(rounds)]
    trace.append("proposals: " + ", ".join(votes))
    winner = max(set(votes), key=votes.count)
    return specialist(winner, text)[0]

question = "the app shows an error when I pay"
for name, fn in [("supervisor", supervisor), ("swarm", swarm),
                 ("hierarchical", hierarchical), ("debate", debate)]:
    trace = []
    answer = fn(question, trace)
    print("%-13s steps=%d  %s" % (name, len(trace), answer))
    print("              trace: " + " | ".join(trace))

Look at the steps number for each pattern. The supervisor takes two hops for every task because everything routes through the centre. The swarm may take one hop or three, depending on where it starts. Debate does the least routing but pays for three model calls. Change question to something with the word "refund" and see how each trace shifts.

Where you will see this

• Coding assistants like Claude Code and Cursor, where a main agent spawns sub-agents to search a large repository in parallel.
• Customer support bots at banks and telecoms, where a router sends you to billing, technical, or new-connection flows.
• Swiggy and Flipkart style shopping assistants, where one agent understands your request and another actually queries the catalogue.
• Deep-research features in chat products, where several agents gather sources and one writes the final answer.
• Internal company bots that answer HR, IT, and finance questions from one chat box.

Common mistakes

• Choosing the topology before the problem. You end up defending an architecture instead of fixing an accuracy issue that a better prompt would have solved.
• No hop limit in a swarm. Two agents can politely pass a ticket to each other forever, and you only find out from the bill.
• Fake hierarchy. Three supervisor layers because it sounds enterprise, when there are really only two teams. Every extra layer adds delay and a new thing that can break.
• Letting the supervisor forward the whole conversation to every specialist. Context fills up, cost rises, and specialists get confused by text meant for someone else.
• Using debate everywhere. It multiplies your cost for tasks where a single careful answer was already fine.

If they ask in an interview

Q: What is the difference between a supervisor and a swarm setup?

A: In supervisor-worker there is one central agent that routes every request to a specialist, and the specialists never talk to each other. In a swarm there is no router at all; agents hand the conversation directly to each other through shared handoff tools. Swarm is faster because of fewer hops, but supervisor is far easier to debug because all decisions sit in one place.

Q: When would you actually justify a hierarchical setup?

A: Only when one supervisor's context window cannot hold the descriptions of all the specialists. At that point you group specialists and put a mini-supervisor over each group. If you have four specialists, a flat supervisor is better; the extra layer only buys you latency and complexity.

Q: Your two-agent swarm keeps bouncing a request back and forth. How do you fix it?

A: Add a hop counter to the shared state and refuse or escalate after a fixed number of handoffs, say three. Then look at why they disagree, which is usually that both agents' descriptions overlap, and tighten the boundary between them.

Try these

1. Take the code above and remove the hop limit in the swarm. Craft a question that makes two agents disagree, and watch it loop. Then put the limit back.
2. Add a fourth specialist for "shipping" and route to it. Notice how much you had to change in the supervisor versus in the swarm.
3. Rewrite the hierarchical function for twelve specialists split into three groups. Write down where a single flat supervisor would have started to struggle.
4. Time all four patterns on a hundred fake questions. Which one wins on number of steps, and which one you would actually ship, and why.

Words, simply

Quick recap

• Four shapes cover almost everything: supervisor-worker, swarm, hierarchical, debate.
• Start with one agent and a plain workflow, and add a shape only when you can say what it fixes.
• Every swarm needs a hop counter, and every hierarchy needs a real reason to exist.