swarmplane 0.0.1

A living task graph for agent orchestration on Google Cloud. Reference implementation.

Swarmplane

A living task graph for agent orchestration on Google Cloud.

An agent run leaves behind two artefacts: whatever state the runtime checkpointed, and whatever trace it emitted alongside. Reconstructing why a run reached its conclusion means reconciling them against each other.

Plan-and-execute designs assert the whole future up front, then flail when step three returns something they didn't anticipate. ReAct loops adapt beautifully but leave behind a transcript — not something you can inspect, diff, or hand to an auditor.

Swarmplane grows the graph from outcomes. Expansion is append-only: a retry is a new node whose parent is the failure, never an edge back to a completed one. The graph stays acyclic, and the complete causal history is preserved by construction.

Two properties follow:

The execution graph is meant to be the audit log. Every node is a span. Every edge is a causal claim. There is no separate trace to reconcile against state — a commitment the implementation has to earn, not a property that falls out of acyclicity.

Every seam is an open protocol. MCP for tools, A2A for agents, A2UI for interface. Nothing proprietary between layers — including Swarmplane itself, which you can remove and keep your agents.

Three opinions

1. The graph is primary, not the agent. Agents are node executors.
2. Every boundary is an open protocol. No proprietary abstraction at any seam.
3. GCP-native, not cloud-agnostic. Portability is not a goal.

Swarmplane is not unopinionated. It is transparent: every decision is visible, inspectable, and replaceable.

"Swarm" here means fleet, not emergence. A plane coordinates workers against a shared graph.

Why the append-only graph makes serverless work

Cloud Run allows a request up to 60 minutes, but a request dispatched through Cloud Tasks is capped at 30. Frameworks that model an agent run as one long-lived process fight that ceiling. Swarmplane has no long-lived process: each expansion is one short request, the graph is durable, and a crash resumes from the frontier. A node parked on a human approval or a remote agent enters waiting — alive, but holding no worker and no open request — so a run can wait six hours without anything running for six hours.

Status

Pre-alpha. Nothing here is stable. Anything on PyPI at 0.0.x is a name reservation, not a release.

The philosophy and architecture writing is live at swarmplane.dev. Implementation has not started — src/swarmplane/ is a package skeleton.

Swarmplane is a reference implementation — a small, deliberately readable codebase meant to be read, copied, and forked. It is installable (uv add swarmplane) so that you can build on the argument, but there is no API-stability promise and there will not be one until the design is proven: the version stays 0.x, and any release may break any API (ADR-0007).

The architecture writing at swarmplane.dev is the primary artifact. The code is the evidence.

Current phase, next steps and open questions: ROADMAP.md.

Repository layout

Path	Contents
docs/	All prose. This is swarmplane.dev.
src/swarmplane/	The reference implementation.
ui/	Graph visualizer and A2UI host.
examples/warehouse-agent/	The flagship demo, with a bundled synthetic dataset.
deploy/	Terraform for Cloud Run, Cloud Tasks, and the graph store.

License

Apache-2.0