Prebuilt Shortcuts: create_supervisor and create_swarm

You built a supervisor triage by hand in Chapter 12: a router, handoff Commands, specialists wired as nodes. Understanding it that way was the point — but writing it out every time is busywork, the same way you wouldn’t hand-roll the model-and-tools loop now that create_agent exists. Two add-on packages generate the standard multi-agent topologies for you: langgraph-supervisor and langgraph-swarm. Because they’re built from the exact handoff mechanism you already know, there’s nothing magic to learn — you’ll recognize what they produce. This chapter shows the shortcuts and, more usefully, when to take them and when to open the hood. Run against langgraph-supervisor 0.0.31 and langgraph-swarm 0.1.0.

create_supervisor

The whole supervisor system from Chapter 12 (router, handoffs, specialists reporting back) collapses to one call. You bring the specialist agents; create_supervisor builds the hub:

from langgraph_supervisor import create_supervisor
from langchain.agents import create_agent

orders = create_agent(model=model, tools=[lookup_order, order_history],
                      name="orders", system_prompt="Handle order status and history.")
recs = create_agent(model=model, tools=[search_catalog],
                    name="recommendations", system_prompt="Recommend books from the catalog.")

supervisor = create_supervisor(agents=[orders, recs], model=model).compile()

Verified: the compiled result is a CompiledStateGraph whose nodes are ['__start__', 'supervisor', 'orders', 'recommendations', '__end__'] — exactly the shape you wired by hand, generated. The supervisor node is a model given handoff tools (one per agent); it reads the conversation, calls the handoff tool for the right specialist, that specialist runs and reports back, and the supervisor decides whether it’s done or needs another. It’s the handoff-tool pattern from Chapter 12, assembled for you.

The best way to trust a prebuilt is to make it show you what it built. Because the result is a plain compiled graph, you can draw it:

print(supervisor.get_graph().draw_mermaid())   # the hub-and-specialists graph, as a diagram

What comes out is the supervisor pointing at each specialist and each specialist pointing back — the picture from Chapter 12, confirming the shortcut generated the structure you expected. And because it’s a normal graph, everything from Act 2 still applies: pass a checkpointer for memory, .stream(...) it, add interrupt_before for a gate. Compared to the hand-built version you dropped the routing function, the Command plumbing, and the edge wiring — maybe thirty lines — for one call, and kept every capability.

create_swarm

create_swarm builds the network topology instead: peers that hand off directly to each other, with no central hub. Each agent carries handoff tools for the peers it can transfer to, and the swarm remembers which agent is currently active across turns:

from langgraph_swarm import create_swarm, create_handoff_tool

alice = create_agent(model=model, tools=[lookup_order, create_handoff_tool(agent_name="bob")], name="alice")
bob   = create_agent(model=model, tools=[create_handoff_tool(agent_name="alice")], name="bob")

swarm = create_swarm(agents=[alice, bob], default_active_agent="alice").compile()

Verified: a CompiledStateGraph with nodes ['__start__', 'alice', 'bob'] — no supervisor node, because in a swarm the agents route among themselves. create_handoff_tool is the packaged version of the handoff tool you wrote by hand; giving alice a handoff-to-bob tool is what lets her transfer the conversation. Two design points fall out of the setup. default_active_agent is where a new conversation starts. And the swarm persists the active agent in state, so a returning user resumes with whoever they were last talking to — the swarm’s memory isn’t just the messages, it’s “who has the floor,” which is exactly what a peer topology needs to stay coherent across turns.

Swarm suits problems where control genuinely flows peer-to-peer — a flight-booking agent handing to a hotel agent handing to a car-rental agent, each taking over when its part comes up — rather than everything routing through one coordinator. It’s more flexible than a supervisor and, as Chapter 12 warned, more prone to handoff loops, so it wants clear “hand off when X, otherwise answer and stop” instructions in each agent.

When to take the shortcut

The prebuilts are thin, honest wrappers: they generate the graph you’d write and hand you back a normal compiled graph you can inspect and extend. Take them when your system is a standard supervisor or a standard swarm, which covers a large fraction of real multi-agent apps. You get less code, a maintained implementation of the fiddly handoff details, and nothing hidden — you verified that yourself by drawing the graph.

Drop back to hand-building (the Chapter 12 and 13 way) when your system isn’t one of those shapes:

• You need non-agent nodes in the flow — a validation step, a mandatory retrieval, a human approval gate at a specific point.
• You need parallel fan-out (Send) among the agents, which neither prebuilt expresses.
• Your routing depends on business rules, not just the model’s judgment — a hard rule that refunds over $100 always go to a human.
• You want a custom state schema the agents share beyond the message list.

The capstone next chapter is exactly this case: it’s supervisor-shaped, but it has a refund approval gate and a SQL path that aren’t plain agent handoffs, so it’s hand-built. Knowing both means you reach for the prebuilt when it fits and open the hood when it doesn’t, and neither is ever a wall — a prebuilt agent can be a node in a hand-built graph, so you can even mix them.

The version caveat

One honest flag, because this series pins versions for a reason. langgraph-supervisor (0.0.31) and langgraph-swarm (0.1.0) are pre-1.0 add-on packages, versioned and released separately from langgraph itself, and they move faster and break more often than the stable core. The concepts are durable — supervisor and swarm are topologies, not APIs — but the exact function signatures here are the most likely thing in this series to have drifted by the time you read it. Pin them, check their changelogs, and lean on the fact that you can always fall back to the hand-built Command version, which lives in the stable langgraph core and isn’t going anywhere. This is the one place in the series where “verified against a pinned version” comes with an asterisk: verified, yes, but against packages that iterate quickly.

Final thoughts

create_supervisor and create_swarm generate the supervisor and network systems from the previous chapters, verified to produce exactly the graphs you’d wire by hand — one hub with specialists, or peers with handoff tools — and you can draw either to confirm it. Take them when your system is a standard shape and you want the code to say so; hand-build when you need non-agent nodes, parallelism, business-rule routing, or a shared custom state; and treat the packages as the fast-moving add-ons they are. You now have every pattern the capstone needs. Time to build it.

Next: the capstone — a complete bookshop support agent that triages to specialists, runs real SQL against the warehouse, and gates refunds behind a human, wiring together everything in the series.