langgraph-swarm routes by handoff and remembers who spoke last
For your multi-agent needs
At a glance
- What is it?
- langgraph-swarm builds multi-agent systems where agents transfer control to each other through tool calls, with the active agent persisted between turns. The library is small, and the checkpointer it depends on is easy to omit.
- Who is it for?
- langgraph-swarm fits a team already on LangGraph whose agents are genuinely specialised and whose conversations run long enough that the last active agent should persist between turns. Reach for the supervisor pattern instead when routing policy is complicated or changes often, since a swarm spreads that policy across handoff tool descriptions with no single place to audit it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 67 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
Handoffs instead of a supervisor, and why the distinction matters
langgraph-swarm is a Python library for building multi-agent systems where agents pass control directly to one another based on what each is good at. There is no coordinator sitting above them deciding who speaks. An agent decides it is the wrong one for the request and hands off.
The second half of the design is the part that makes it usable: the system remembers which agent was last active, so the next message in a conversation resumes with that agent rather than starting the routing decision again. That single property is what separates a swarm from a set of agents that happen to call each other.
This is for developers already building on LangGraph who have a problem shaped like specialisation: a billing agent and a technical support agent, a research agent and a writing agent. If your work is one capable agent with many tools, this adds structure you do not need.
Two functions carry the whole library
The public surface is small, which is the strongest thing about it. One function creates the swarm from a list of agents and a named starting agent. Another creates the handoff tool that one agent uses to transfer to another. The agents themselves are ordinary LangGraph agents built by the standard constructor, given a name and a set of tools.
A handoff is therefore just a tool call. An agent is told about a tool whose description says it transfers to a colleague, and the model decides to call it the same way it decides to call a calculator. That is an elegant fit with how these models already work, and it means the routing logic lives in tool descriptions rather than in a separate control structure you have to maintain.
What the swarm builder returns is a graph that has not been compiled yet, which is the seam where persistence gets attached. The example in the README defines two agents, one that can add numbers and one instructed to speak like a pirate, each holding a handoff tool pointing at the other, and then composes them.
Installing it and wiring the first two agents
The package installs on its own from the index.
pip install langgraph-swarmRunning the documented example needs a model provider alongside it, and the README's quickstart pairs it with the OpenAI integration package. An API key goes in the environment before you run anything.
pip install langgraph-swarm langchain-openaiWith both installed, the assembly step is short and shows where persistence attaches. The swarm is built from the agent list with an explicit starting agent, and the resulting graph is compiled with a checkpointer.
checkpointer = InMemorySaver()
workflow = create_swarm(
[alice, bob],
default_active_agent="Alice"
)
app = workflow.compile(checkpointer=checkpointer)Invoking the compiled application with a thread identifier in the configuration is what makes successive calls part of one conversation. In the README's walkthrough, the first message asks to speak to Bob and the second asks an arithmetic question, which demonstrates the handoff and then the return path in two turns.
The checkpointer is the part people will get wrong
The README marks this as important, and it is the single most consequential detail in the library. Without a checkpointer, the swarm forgets which agent was last active and loses the conversation history.
Consider what that produces in practice. The system will work perfectly in a single turn test, which is how most people first try a library. Handoff fires, the right agent answers, everything looks correct. The failure appears only on the second message, when the swarm has forgotten the handoff ever happened and routes from the default agent again. That is a bug that survives a demo and breaks in use.
Two kinds of persistence are supported and they are not interchangeable. A checkpointer holds short term state, meaning the thread of one conversation. A store holds long term state across threads. Both attach at the same compile step, and the distinction is worth getting right early, because retrofitting cross-conversation memory later means revisiting how state is keyed.
Customising handoffs, and the full history default
The built in handoff tool is a starting point rather than a constraint, and the README documents what is worth changing. You can rename the tool and rewrite its description, which is the actual routing logic since the model chooses based on that text. You can add arguments for the model to populate, and the suggested one is a task description so the receiving agent is told what to do rather than inferring it from context.
The default worth examining is what crosses the boundary. By default a handoff passes the full message history, every message generated in the swarm up to that point, plus a tool message recording the transfer. That is the safe choice because nothing is lost, and it is expensive because each handoff carries the accumulated conversation into the next agent's context, which grows with every transfer.
The custom tool example in the README shows the mechanism for changing that: a tool returning a command that targets the receiving agent in the parent graph and supplies the state update, including which messages to carry and which agent becomes active. Anyone running a swarm where agents hand off repeatedly should treat trimming that payload as the first optimisation, and the library leaves the door open for it rather than hiding the behaviour.
Swarm against supervisor is the real decision
The alternative from the same ecosystem is the supervisor pattern, where a coordinating agent receives every request, decides which specialist should handle it, and takes control back when that specialist finishes.
The difference is where routing knowledge lives and what it costs. In a supervisor system, one place knows the roster, which makes policy easy to change and easy to audit: you rewrite the supervisor's instructions and every routing decision moves with it. The price is an extra model call on the path of every request, and a bottleneck that has to understand all the work well enough to dispatch it. In a swarm, routing knowledge is distributed across handoff tool descriptions, so there is no extra hop and an agent transfers only when it decides to. The price is that adding a fifth agent means telling the other four it exists, and that a badly worded description produces a transfer nobody can see the reason for.
Choose the supervisor when routing policy is complex, changes often, or must be inspected in one place. Choose this when conversations are long and sticky, when the specialists are genuinely distinct, and when the extra dispatch call on every turn is a cost you would rather not pay. The persistence of the active agent between turns is the feature that makes the swarm form worth it, so if your interactions are one-shot, most of that advantage disappears.
Release history, the LangChain 1.0 migration, and licensing
The library is MIT licensed, which for an ecosystem component is what you want and rarely raises a question.
The release history is short and points in a clear direction. Version 0.0.15, published on 2025-11-07, allowed the library to be used with LangChain 1.0, and version 0.1.0, published on 2025-12-04, completed the migration, both arriving as outside contributions. That sequence matters for anyone adopting now: the library crossed a major version boundary in its main dependency, so examples and tutorials written before that point may use the older import paths. The last push to the repository was on 2026-07-15.
Upgrade cost is dominated by the thing underneath rather than by the library itself. A package this small, built on a fast moving framework, inherits that framework's pace. The repository carries a tests directory, an examples directory, a Makefile and a lock file, so reproducing its own environment is possible, which is the practical way to establish what a given version expects.
Editorial conclusion
langgraph-swarm fits a team already on LangGraph whose agents are genuinely specialised and whose conversations run long enough that the last active agent should persist between turns. Reach for the supervisor pattern instead when routing policy is complicated or changes often, since a swarm spreads that policy across handoff tool descriptions with no single place to audit it. Before shipping, compile the graph with a checkpointer and test a second turn rather than a first, because without one the swarm forgets which agent was active and silently routes from the default again, and check which LangChain version your examples assume, since the 0.1.0 release of 2025-12-04 completed the migration to LangChain 1.0.
Frequently asked questions
What is a swarm in langgraph-swarm?
It is a multi-agent architecture where agents hand control to one another directly based on their specialisations, rather than being routed by a coordinator. The system records which agent was last active so later messages resume with that agent.
Do I need a checkpointer with langgraph-swarm?
Yes for any multi-turn use. The README states that without short term memory the swarm forgets which agent was last active and loses the conversation history, and advises always compiling with a checkpointer for multi-turn conversations.
What is the difference between langgraph-swarm and a supervisor architecture?
A swarm distributes routing across handoff tools that agents call themselves, so control passes peer to peer with no extra dispatch step. A supervisor centralises that decision in one coordinating agent, which makes policy easier to change in one place at the cost of a routing call on each request.
How much context is passed during a langgraph-swarm handoff?
By default the handoff tool passes the full message history generated in the swarm up to that point, plus a tool message recording the transfer. The README documents writing a custom handoff tool if you want to change what is carried across.
Community notes