Skip to content

A living task graph for agent orchestration on Google Cloud

Swarmplane records an agent run as a graph that grows from outcomes — append-only, acyclic by construction, meant to be read as the audit log of what actually happened.

Read the argument Explore the architecture

One run, end to end

%%{init: {"flowchart": {"rankSpacing": 34, "nodeSpacing": 26, "padding": 8}}}%%
graph LR
    T(Task: monthly revenue by region) --> S(Inspect schema)
    S --> Q1(Draft SQL v1)
    Q1 --> F("Failed: no column 'region'")
    F --> D(Discover: region lives in dim_store)
    D --> Q2(Draft SQL v2 with join)
    Q2 --> R(Validated result)

    %% LR, not TD: this renders inline in the philosophy essay's ~688px column,
    %% where the SVG scales down to fit (~0.76 today). Every node added to the
    %% chain shrinks the whole strip there — check that page before growing it.
    %% Semantic color lives in the stroke, not the fill: Material themes node
    %% fill and label color per scheme (light/dark) via --md-mermaid-* variables
    %% and overrides classDef `color:`, so a colored fill cannot guarantee
    %% readable labels in both schemes. A colored border can.
    %% NOTE: every comment line needs content after `%%` — a bare `%%` line is
    %% parsed as a node and renders as a stray box labelled "%%".
    %% `start` is a mid-copper, not --sp-accent: a classDef takes one literal for
    %% both schemes, and neither accent token survives the other background
    %% (#a2561f is 2.7:1 on dark, #d9915b is 2.6:1 on light — both under 3:1).
    %% #c07a3e sits between them at 5.5:1 dark / 3.3:1 light. Do not "fix" it
    %% back to the token.
    classDef start stroke:#c07a3e,stroke-width:2.5px
    classDef fail stroke:#c9705f,stroke-width:2.5px
    classDef ok stroke:#5e8f6c,stroke-width:2.5px
    class T start
    class F fail
    class R ok

The failed query is not erased and retried in place. It sits in the graph as the parent of the discovery it caused — so the final result can say why it looks the way it does.

Three opinions

The graph is primary, not the agent

Agents are node executors. The run's structure — what happened, in what order, caused by what — is the first-class object.

Every boundary is an open protocol

No proprietary abstraction at any seam — including Swarmplane itself, which you can remove and keep your agents.

GCP-native, not cloud-agnostic

One platform, taken seriously. Portability is not a goal.

Swarmplane is not unopinionated. It is transparent: every decision is visible, inspectable, and replaceable. Each opinion is stated with what it costs — disagreeing with any of them is a good reason to use something else.

Every seam is an open protocol — MCP for how agents call tools, A2A for how they hand work to other agents, A2UI for how an agent describes an interface.

Where to start

  1. The argument — the whole idea in one essay.
  2. The Living Graph — the claim everything else rests on.
  3. Prior Art — an honest account of what is and isn't new here.

Pre-alpha. Swarmplane is a reference implementation: a small, deliberately readable codebase meant to be read, copied, and forked. It is installable so you can build on the argument, but there is no API-stability promise — the version stays 0.x, and anything on PyPI at 0.0.x is a name reservation, not a release.