Why SwarmPlane

An agent that does real work has to do six things: take a task, decide what steps it implies, run those steps as agents, call tools, show a human what is happening, and reach that human wherever they are.

task → graph → agents → MCP → A2UI → channel

Every one of those layers has a good solution today. Two things are still missing, and they turn out to be the same thing.

Problem one: the stack is fragmented

You can assemble the whole thing right now. LangGraph or ADK for orchestration, MCP servers for tools, AG-UI or A2UI for the interface, a Slack or WhatsApp adapter for the channel. People do this, and it works.

What you get at the end is a system where no single artefact describes what a run did.

The orchestrator holds graph state. The MCP client holds tool call logs. The UI layer holds an event stream. The channel adapter holds message history. Your tracing backend holds spans that reference all four but belong to none of them. When something goes wrong — and the interesting failures are always cross-layer — answering "what happened" means correlating five sources that were never designed to be correlated, each with its own identifiers and its own notion of time.

The cost of assembling the stack from parts is not integration effort. Integration is a weekend. The cost is that the composed system has no memory of itself.

Problem two: frameworks invert control

A library you call. A framework calls you.

That inversion is what makes frameworks productive early — you write a node function, the runtime handles scheduling, retries, persistence and streaming. It is also what makes them expensive later. Your code is a callback. The stack trace is mostly the framework's. The state lives in objects you did not define. And when your requirement does not fit the abstraction, you are not extending a system, you are negotiating with one: monkey-patch it, fork it, or reshape your problem until it fits.

This is not a defect of any particular framework. It is what the framework form factor is, and it is the honest price of the productivity it buys.

To be fair about a common but outdated complaint: dependency bloat is not the issue. Resolved with uv on 2026-07-26, langgraph 1.2.9 pulls 35 transitive packages and langchain 1.3.14 pulls 36 — against 31 for the bare minimum an agent runtime needs (mcp 1.28.1 plus pydantic). LangGraph declares six direct runtime dependencies, four of which are its own subpackages.

The bloat reputation is real but predates the langchain-core and partner-package split, which fixed it. Repeating that criticism today describes a version that no longer ships — and SwarmPlane, once it carries a2ui, OpenTelemetry, a web server, a database driver and a CLI, will very likely resolve more packages than LangGraph does. This project does not compete on dependency count and should not be read as claiming to.

Why this bites hardest in production

Conventional debugging assumes reproduction. Set a breakpoint, run it again, watch it happen.

Agent runs do not reproduce. The failure occurred once, at 3am, for one user, against a model that will answer differently next time. You cannot breakpoint it, and stepping through framework internals — however readable they are — is the wrong tool for a fault you cannot re-trigger.

So "easier to step through" is a weak benefit, and a framework that offered it would still leave you stuck. The useful question in production is never what is this code doing right now. It is what did that run actually do, and why.

Both problems have the same shape

Fragmentation means no artefact describes the run. Inversion of control means no artefact describes the decisions. In both cases the missing thing is a durable record of what happened.

The move

Make one layer primary and express the others as consequences of it.

SwarmPlane makes the graph primary. A tool call is a node effect. An agent dispatch is a node effect. A UI emission is a node effect. A channel delivery is a node effect. The graph is the only mutable state in the system, which means it is also the only thing you have to look at to know what happened.

That answers problem one directly: there is one artefact, and it spans every layer.

It answers problem two by changing what debugging means:

The artifact is debuggable, not the code path. You do not attach a debugger. You read the graph.

Every node carries what it was asked to do, what it returned, and what it cost. Every edge is a causal claim. The run that failed at 3am left a complete record of itself, readable afterwards, without reproduction. See The Living Graph.

And the form factor answers the rest

There is a part of the inversion-of-control problem that no framework can solve, because solving it means not being a framework.

SwarmPlane is a reference implementation: a small, deliberately readable codebase meant to be read and copied, not imported. If the code lives in your repository, there is no framework to debug through, no version to fight, and no upstream to wait on. You step into your own code because it is your own code.

This is not a claim to be more readable than the alternatives. It is a different relationship to the code, with different costs — listed below.

Three opinions

These are not hedged. Disagreeing with any of them is a good reason to use something else.

1. The graph is primary, not the agent. Most frameworks treat the agent as the unit of composition and let structure emerge from how agents call each other. SwarmPlane inverts this: the graph is the object, agents are node executors. The cost is that agent-centric patterns — an agent that owns a long conversation, say — are less natural to express.

2. Every boundary is an open protocol. MCP for tools, A2A for agents, A2UI for interface. No proprietary abstraction at any seam. You inherit the limitations and version churn of specs you do not control. See Protocols, Not Abstractions.

3. GCP-native, not cloud-agnostic. The design assumes Cloud Run's execution model, Cloud Tasks for scheduling, and Postgres for the graph store. Portability is not a goal and will not be accepted as a constraint. Cloud-agnostic designs converge on the intersection of every cloud's features, and that intersection is where good ideas go to become configuration.

What this costs

Being copied rather than imported is a trade, not a free win.

Copied code receives no upstream fixes. This is the big one. When a framework patches a race in its scheduler, every user gets it on the next release. When SwarmPlane patches one, you get it if you happen to notice and merge it by hand. Centralised bug fixing is a substantial part of what frameworks are for, and this design gives it up deliberately.

You own the code, including its bugs. Full control and full responsibility are the same sentence read twice.

No ecosystem. No plugin directory, no community integrations, no Stack Overflow answers. LangGraph's years of production hardening are real value that a reference implementation cannot substitute for.

No stability promise. There is no semver contract and there will not be one until the design is proven.

If those costs read as unacceptable, that is a correct reading of your situation and you should use ADK or LangGraph. Both are good, both are more complete, and neither is the wrong answer for most teams.

What this is not

Not unopinionated. The three above are strong opinions and the whole system is shaped by them. The claim is transparency — every decision is visible, inspectable, and replaceable — which is a narrower and more defensible thing than flexibility. See Transparency Over Magic.

Not complete. SwarmPlane has an argument and enough code to test it. If you need a supported platform today, you need somebody else's.

On the name

"Swarm" means fleet, not emergence. Nothing here is intentionally non-deterministic, and no behaviour is expected to arise from agents interacting without supervision. A plane — as in control plane — coordinates a fleet of workers against shared state. The shared state is the graph.