Getting started

Fifteen minutes from nothing to a run that survives a crash, replays exactly, and refuses to rewrite its own history.

Every snippet here is either lifted from a working example in examples/ — which CI runs on every push — or from the crate’s own compile-checked rustdoc. If one does not build, that is a bug worth reporting.

The order is deliberate. Sections 2 and 3 are two doorways onto the same guarantees, and the first one needs no Rust at all. It comes first because it needs nothing but a file; the compatibility promise attaches to the evidence both doorways produce — the record, the export and the operator vocabulary — not to either doorway. Writing skills in Rust buys expressiveness and takes the ordinary pre-alpha risk on function signatures.

1. See it work first 👀

Before writing anything, run the thing that demonstrates the whole claim:

git clone https://github.com/hupe1980/agentplane
cd agentplane
cargo run --example durable_pipeline

1. live run      → Succeeded
   external calls: 3

2. strict replay → Succeeded
   external calls: 3 (unchanged: true)

3. run crashed   → Failed("simulated crash after stage 0")
   external calls: 1
   resumed        → Succeeded
   external calls: 3 — stage 0 was replayed, not repeated

4. changed build → Quarantined("non-determinism at seq 8: expected ek:cf87…")

5. all journals verify — no record was altered after the fact

Read those five lines slowly, because they are the product:

• 2 — replaying performed nothing. The counter did not move.
• 3 — the crash resumed at stage 1. Stage 0 ran once across both attempts, not twice.
• 4 — a different build replaying an old journal is quarantined. It is not silently accepted, and it is not a crash to recover from. Changing code and crashing are different things, and only one of them is recoverable.

2. An agent with no Rust 📄

If the agent is a prompt, a model and a result shape, it needs no program at all — a file and a key are the whole thing. (Prefer to build this up one command at a time, with each refusal explained as you hit it? That is your first agent, the step-by-step tutorial; this section is the condensed version.)

# summariser.yaml
apiVersion: agentplane.hupe1980.github.io/v1alpha1
kind: Agent
metadata: { name: summariser, version: "1.0.0" }
spec:
  execution: { kind: completion }
  identity:
    role: "Summarise a support ticket"
    constraints: "One sentence. No speculation."
  capabilities: { provides: [support.summarise] }
  models:
    privileged: { provider: fake, model: sum-1 }
  output:
    schema:
      type: object
      additionalProperties: false
      required: [summary]
      properties: { summary: { type: string } }
  budgets: { max_tokens: 10000 }

cargo install agentplane --features cli

agentplane init agent.yaml              # or start from a starter that validates
agentplane validate summariser.yaml
agentplane digest   summariser.yaml     # what a registry pins
agentplane run      summariser.yaml --input '{"ticket": "printer on fire"}'
agentplane schema                       # the format as a JSON Schema

For editor autocomplete and inline errors while writing the file, put the published schema in a modeline — see the manifest reference:

# yaml-language-server: $schema=https://hupe1980.github.io/agentplane/agent.schema.json

--input - reads stdin, the convention every pipe-shaped tool honours. A recorded run is re-executed with its own verb — agentplane replay <run-id> --store runs.redb --manifest summariser.yaml, plus --strict to verify rather than resume, under the same manifest or an edited one — and agentplane card <manifest> --url <base> prints the Agent Card a served manifest would advertise, so what a peer will see is reviewable before anything listens on a socket.

Or with no Rust toolchain at all, which is rather the point of a tier whose premise is a file and a key are the whole agent:

docker run --rm --read-only --network none -v "$PWD:/work:ro" \
  ghcr.io/hupe1980/agentplane \
  run /work/summariser.yaml --input '{"ticket": "printer on fire"}'

--read-only --network none are not decoration — they are the check that the claim below is true. The default journal is in memory and the fake driver needs no network, so the first run needs neither a disk nor the internet, and the image’s own smoke test runs exactly this way rather than taking that on trust.

The image is distroless, nonroot, has no shell, and is published multi-arch, cosign-signed and with SLSA provenance and an SBOM bound to the digest. :slim — the default and :latest — carries every model provider; :full adds MCP, the A2A peer server, the operator HTTP surface, Cedar, key rings, governed media and Postgres. The split is about surface, not size: they are within a megabyte of each other, and the reason to run :slim is that it does not contain an HTTP server or a database client at all.

Tools, still without Rust

execution.kind: tool-calling runs the loop from a file, and a loop needs tools. The manifest grants tool://tickets/read; which transport reaches tickets is named on the command line, exactly as a model’s base URL is:

agentplane run examples/tool-calling.yaml \
  --input '{"ticket": "T-1"}' \
  --mcp "tickets=python3 examples/mcp-server.py"

That split is deliberate. An agent’s declaration — and therefore its digest — must not change when it moves between a laptop and a cluster, so grants are reviewed and wiring is deployed. A grant naming a server nobody wired is refused at build, in the same breath as a grant nothing implements:

'tickets/read' is granted but nothing implements it and no transport is wired
for server 'tickets' — the model will be offered a tool that fails when chosen

--mcp runs a command, and that is worth being explicit about: it is not an escalation over what the caller already had — the operator typed it on the same line as the manifest path — and nothing in a run’s data path can reach it. A manifest, a model and an A2A peer all cannot choose a server; only argv can. The command is split on whitespace and no shell is involved: no globbing, no pipelines, no $(...). Needs --features cli,mcp-stdio, or the :full image.

One constraint worth knowing before you reach for the image. :full has mcp-stdio compiled in, and a distroless image has no interpreter and no shell — so the npx- and Python-based servers most of the MCP ecosystem publishes cannot run inside it. Only a statically linked server binary mounted into the container can. That is the price of a base image with no package manager, and it is a real trade rather than an oversight: run the CLI on a host that has the runtime your server needs, or ship your MCP server as a static binary. The container smoke test asserts the image has no interpreter, so if a base image ever gains one, that assumption fails loudly instead of drifting.

Hosting it, still without Rust

A manifest can also be served — the A2A 1.0 peer surface that passes the protocol project’s own conformance kit, an MCP listener a framework calls tools on, and the operator API — started from the same file.

From nothing to a governed call

Six commands take a machine with git, docker and uv to a framework’s tool call that the plane admitted, journaled and answered, with no model key. Each line is one command, run in order from an empty directory:

git clone --depth 1 https://github.com/hupe1980/agentplane
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/hupe1980/agentplane:full init --serve plane
docker compose -f plane/compose.yaml up --wait
export AGENTPLANE_TOKEN="$(cat plane/framework.token)"
cd agentplane/examples/frameworks/pydantic-ai
uv run --no-project --python 3.12 --with-requirements requirements.lock quickstart.py

The last two run any of the five quickstarts below; change the directory. init --serve writes seven files into plane/: the starter agent on the fake provider, the shipped policy, a token file with three freshly generated callers (peer-1, framework-1, ops-1), the framework caller’s token alone, a generated Postgres password, the plane’s connection string holding it (store.env), and a compose file that runs the plane against Postgres. The four secret files are mode 0600. It refuses if any of the seven exists, and removes what it wrote if it fails partway. Run it as the user the plane should run as: the container runs as the token file’s owner, and init --serve refuses to write a plane that would run as root. The plane serves A2A on 127.0.0.1:8080, MCP on 127.0.0.1:8081 and the operator API on 127.0.0.1:9090; the token file is mounted as a secret, never passed in the environment, and no secret is on a command line. To serve other machines, publish 8080 and 8081 on an address they reach and set --url and --mcp-allowed-host to the names they use — the compose file says where.

Each is one file that imports nothing of this project. requirements.txt pins its framework exactly; requirements.lock pins the whole dependency closure with hashes, which uv pip install --require-hashes -r requirements.lock checks — how CI installs every one before walking it against the :full image. With no QUICKSTART_MODEL set, each drives the framework’s own MCP client without a model key; set it (with that provider’s key) and the framework’s model decides. The A2A half runs when AGENTPLANE_PEER_TOKEN holds the peer-1 token. The plane governs the tool call, not the framework’s loop.

By hand

# The shipped token file holds placeholders `serve` refuses: generate the tokens.
sed -e "s/replace-me:peer-a:openssl-rand-hex-32/$(openssl rand -hex 32)/" \
    -e "s/replace-me:ops-alice:openssl-rand-hex-32/$(openssl rand -hex 32)/" \
    -e "s/replace-me:app-1:openssl-rand-hex-32/$(openssl rand -hex 32)/" \
    examples/serve-tokens.yaml > tokens.yaml

agentplane serve examples/served.yaml \
  --url http://localhost:8080/a2a \
  --policy examples/serve-policy.cedar \
  --tokens tokens.yaml \
  --operator-addr 127.0.0.1:9090 \
  --mcp-addr 127.0.0.1:8081 \
  --store ./served.redb

curl http://localhost:8080/.well-known/agent-card.json
curl "http://localhost:9090/runs?outcome=quarantined" -H 'authorization: Bearer …'

serve refuses a token shorter than 32 bytes, and it refuses the file’s placeholders by name: a credential copied out of a public repository is one every reader holds. The bearer for the operator surface is the ops-alice line of tokens.yaml.

That second URL is the point of --operator-addr. Every conclusion this runtime reaches is meant to be queryable by whoever must clear it rather than merely emitted. It is off unless asked for and on its own listener: the public address is the one a peer holds, and putting the worklist and task decisions behind it is one policy mistake away from a peer reading every run.

The separation is enforced by policy, not by the port. In serve-policy.cedar the peer role reaches the A2A actions and the operator role the API ones, so a peer token that reaches the operator socket is still refused — the separate port is defence in depth rather than the control itself.

--mcp-addr serves every agent in the file as MCP tools over Streamable HTTP, at http://127.0.0.1:8081/mcp — the URL and bearer header an agent framework in any language is configured with. Same token file, same policy, asked as mcp:* actions: the app-1 line’s framework role reaches them. A call is admitted as that caller, and its arguments arrive as untrusted data from peer:app-1. It needs the mcp-server-http feature, which the :full image has; MCP, being served has the rest.

What the shipped policy grants. peer reaches the A2A actions a peer needs, framework the mcp:* caller actions, and operator the read and task verbs plus the on-call verbs — api:halt.place, api:halt.lift, api:run.cancel, api:run.abandon, api:effect.reconcile, api:hold.place, api:hold.release — so an incident is not the first time a verb is denied. It does not permit data:release, so a run that reaches a typed release is refused: which labels may leave is a deployment’s decision, and the file carries the rule to uncomment beside the release gate it controls. Cedar denies what no rule permits, and the caller is told only that it was declined.

--push-host <host> (repeatable) turns on A2A push notifications to that exact host. Without one, push is not wired and the Agent Card advertises it as absent rather than claiming a capability nothing serves. That flag is the whole of the configuration: PushSender owns HTTPS-only, the all-answer public-IP check, DNS pinning, manual redirects, the timeout and secret redaction; what an operator decides is where, which is the one thing the crate cannot. The grant is checked at registration as well as at delivery, so a peer learns straight away:

this deployment does not permit webhooks to 'evil.example.net'
a webhook URL must be https — the payload describes a task, and sending it in
clear to an address the recipient chose is a disclosure

Note the ordering: a peer also needs a2a:task.push in the policy set, and that gate runs first. A policy that omits it declines with the uniform this request was not permitted, saying nothing about the URL — which is correct, and worth knowing when a webhook registration is refused for a reason that looks nothing like a webhook problem.

A served plane also sweeps: deadlines warn and breach, tasks expire, dead letters are retired, and due timers fire, every --sweep-every seconds (30 by default, 0 to drive it from your own scheduler). Without it an agent that calls cx.sleep, waits on an event, or opens a human task would be accepted and then never make progress — a suspended run is a row, and something has to come back for it.

And it drains. SIGTERM or SIGINT stops it accepting, answers what it has in hand, and gives the runs already executing --drain-secs (25 by default) to finish. Without that a deploy cuts runs mid-tool-call, which the journal can only report as this call may or may not have happened — see stopping an instance.

Four things are refused rather than defaulted, and each refusal is the design:

• --policy — a Cedar policy file, or a bundle directory. A permissive engine and no engine are the same behaviour, and only one of them looks governed.
• --tokens — bearer tokens naming callers. A server that authenticates nobody has no actor to record a decision against; an unknown credential is refused rather than becoming an anonymous caller. An entry may carry a scope (and a not_after), which becomes that caller’s own delegation chain: every run it starts is admitted under it and recorded as acting for the caller, not for the plane.
• --store — a served task’s id is a promise it can be fetched again, and an in-memory journal breaks that promise at the next restart. run may journal to memory because it exits with its answer.
• A room — A2A serves the file’s one topology.role: orchestrator, and refuses a room without exactly one, because A2A’s card path is well-known and singular. --mcp-addr serves every agent in it, or those --mcp-agent names.

served.yaml differs from summariser.yaml in two places. spec.input is the shape a caller is offered, which serving over MCP requires. The interesting one is security.max_sensitivity_egress: internal. A message from a peer arrives labelled Internal — it came from outside — while --input on your own command line arrives Public. Without that line the peer’s text cannot reach the model, and the run fails with sensitivity Internal exceeds sink ‘model.complete’ ceiling Public. An agent that may talk to strangers says so in the reviewed file rather than acquiring the permission by being put behind a socket.

Needs --features cli,a2a-server,cedar; a build without them says so and names the flag. The :full image is built with them.

This exact file uses the deterministic fake driver, so the first run needs no API key and no network. To go live, change the provider and model in the file (that intentionally changes its digest) and export the matching key: the cli feature already carries every model provider, Bedrock included.

A file may hold several manifests separated by ---, exactly as Kubernetes packages resources — so a multi-agent room (an orchestrator granted its specialists as tool://agent/... tools) deploys and runs as one file with no Rust anywhere. Each document keeps its own digest: the file is packaging, not identity. agentplane run room.yaml starts at the room’s one declared orchestrator; say --capability when the file leaves any doubt.

Every verb takes only its own flags — agentplane run --push-host … does not parse, because the flag lives on serve’s struct. Deployment wiring also reads AGENTPLANE_STORE, AGENTPLANE_TENANT, AGENTPLANE_URL, AGENTPLANE_POLICY, AGENTPLANE_TOKENS, AGENTPLANE_ADDR, AGENTPLANE_OPERATOR_ADDR, AGENTPLANE_SWEEP_EVERY, AGENTPLANE_DRILL_EVERY, AGENTPLANE_DRAIN_SECS and AGENTPLANE_LOG_FORMAT, with the flag winning when both are given — one rule, rather than a config file and a precedence table. agentplane <verb> --help is generated from the same structs that enforce the flags, so it cannot describe an option nobody implemented.

The answer goes to stdout and everything else to stderr, so it pipes. A run that is refused, exhausted or failed exits 1, because whoever scripts this needs the shell’s own answer to “did it work”. A run that stopped to wait — for a person, a timer or an event — exits 3, neither an answer nor a failure, and prints what it waits for and the commands that move it on, naming the store and the tenant it ran on (a postgres:// password is left out; a store taken from AGENTPLANE_STORE is printed as that variable). A command this binary refuses exits 2, a store it cannot reach 4, and an answer --limit cut short 5 — the whole table is at the foot of agentplane --help and in operations.

Every run opens or joins a case, because oversight, obligations and $correlation/<namespace> memory subjects all live on one. With no --correlate the run gets a case of its own; --correlate customer=C-7 (repeatable) joins the open case that key belongs to. So a manifest with spec.oversight runs from a terminal end to end — examples/approval.yaml is one:

agentplane run examples/approval.yaml --input '{"ticket": "T-1"}' --store runs.redb
# run run_01… is waiting for a person to decide task_…   (exit 3)
agentplane tasks  --store runs.redb                      # the worklist
agentplane decide task_… approve --reason "checked" --actor ada --store runs.redb
agentplane replay run_01… --manifest examples/approval.yaml --store runs.redb
agentplane history run_01… --store runs.redb             # its journal, record by record

A run that calls an A2A peer (--peer) also needs --acting-as <subject>: a peer call is made on somebody’s behalf, and the flag names whose. --peer needs the a2a feature, and --mcp needs mcp-stdio → which verb needs which feature.

Keys come from the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY — or GOOGLE_API_KEY), never from the file; Bedrock uses AWS_REGION and AWS’s standard credential chain (SSO, roles and aws login sessions included) or a Bedrock API key in AWS_BEARER_TOKEN_BEDROCK, and a local or Hugging Face model is provider: chat-completions with CHAT_COMPLETIONS_BASE_URL pointing at any OpenAI-compatible server — Ollama, TGI, vLLM, llama.cpp, or https://router.huggingface.co/v1 with CHAT_COMPLETIONS_API_KEY=$HF_TOKEN. An agent’s declaration must not change when its credential does. And only the providers the manifest names are registered — otherwise exporting the wrong variable would make the agent runnable on a model its declaration never named.

Trying it on a page

redb admits one writer process, so while something holds the store the verbs above are locked out of it. agentplane dev holds it and carries them: it builds the plane exactly as run does and serves one page for it.

agentplane dev examples/approval.yaml
# http://127.0.0.1:53817/#t=…

Open the printed URL. The page lists every run in the store with its status, and for the one you pick:

• shows what its model is writing, as it writes it;
• shows its journal as a timeline, filterable and expandable record by record, or as the conversation its model calls held — hidden characters shown as \u{…}, each call with its duration, each consultation linked to the sub-run that answered it;
• starts, cancels and re-runs runs (the input pre-filled from the agent’s declared schema), and delivers the event a run waits for;
• decides tasks — a consultation’s approval showing what the consulted agent may do, a call’s approval taking amended arguments;
• strict-replays a run, or every run, against the file as it is now, and exports the store beside the export’s verification.

Saving the manifest rebuilds the plane; a file that does not parse leaves the running one in place and says why.

It is for the agent’s author on their own machine — not a deployment surface, not a reviewer page and not an editor. It listens on loopback only, behind a token minted per process; keeps its journal in memory, or in a `–scratch

cargo add agentplane
cargo add serde_json
# The runtime is async, and which executor runs it is yours to choose — so
# tokio is not re-exported. `async_trait` is: writing a skill starts at the
# prelude, not in Cargo.toml.
cargo add tokio --features macros,rt-multi-thread

cargo add agentplane --features postgres,http,mcp,providers,bedrock,media,cedar,signing

warning: ignoring agentplane@0.6.0 (which requires rustc 1.94.1)
         to maintain <your crate>'s rust-version of 1.94

use agentplane::prelude::*;
use serde_json::{Value, json};

#[derive(Debug)]
struct Greet;

#[async_trait]
impl Skill for Greet {
    // No `.provides(..)`: a skill that declares nothing answers its own name.
    fn descriptor(&self) -> SkillDescriptor {
        SkillDescriptor::new("greet")
    }

    async fn invoke(
        &self,
        cx: &mut StepCtx<'_>,
        input: Tainted<Value>,
    ) -> Result<Outcome, SkillError> {
        // `now()` is a journaled effect: on replay it returns the recorded
        // instant rather than reading the clock again.
        let at = cx.now().await?;

        Ok(Outcome::done(input.map(|v| json!({
            "greeted": v,
            "at": at.to_string(),
        }))))
    }
}

// Everything below is already in scope from the prelude imported above.
use std::sync::Arc;

let store: Arc<dyn JournalStore> = Arc::new(RedbStore::open_in_memory()?);

let runtime = Runtime::builder(Arc::clone(&store))
    .owner("my-service")
    .skill(Greet)
    .build();

let outcome = runtime.run("greet", Tainted::trusted(json!({ "name": "world" }))).await?;
println!("{:?} → {:?}", outcome.status, outcome.output);

// Re-executes the logic, reads every effect back. Nothing is performed again.
let replayed = runtime.replay(outcome.run_id, Mode::Strict).await?;
assert_eq!(outcome.output, replayed.output);

Error: no skill provides capability 'demo.greeet' — this plane provides:
demo.greet. `run` takes a capability, not a skill name; a skill declares its own
with `SkillDescriptor::new(..).provides(..)`

use agentplane::prelude::*;
use agentplane::tools::ToolFailure;
use serde_json::{Value, json};

/// Post one entry to the ledger.
#[derive(Debug, serde::Deserialize, agentplane::schemars::JsonSchema)]
#[schemars(crate = "agentplane::schemars")]
struct PostEntry {
    account: String,
    memo: String,
}

#[async_trait]
impl Tool for PostEntry {
    const SERVER: &'static str = "ledger";
    const NAME: &'static str = "post_entry";

    async fn call(self) -> Result<Value, ToolFailure> {
        Ok(json!({ "posted": self.account, "memo": self.memo }))
    }
}

  tools:
    - ref: "tool://ledger/post_entry"
      mutates: true
      description: "Post one ledger entry."
      protected_fields:
        - path: /account
          require_trusted: true

use agentplane::tools::ToolId;

let args = Tainted::object([
  ("account", Tainted::trusted(json!("receivables"))),
  ("memo", model_written_memo), // may remain untrusted
]);
let result = cx
  .call_tool(ToolId::new("ledger", "post_entry"), args)
  .await?; // exact bytes, protected account

let args = cx.release(
  args,
  Release::fields(
    ReleaseScope::trust(),
    ["/account"],
    "operator matched the account to settlement SET-42",
    "tool://ledger/post_entry",
    ["approval:SET-42"],
  ),
).await?;

use agentplane::core::{Expiry, TaskSpec};

let decision = cx.task(
    &TaskSpec::new("rejection-handling", justification, "decision")
        .role("ops")
        .excluding("agent:proposer")   // four eyes; the run's own requester is barred already
        // Escalation carries who it widens to: the roles are part of the answer.
        .on_expiry(Expiry::escalate_to(["ops-lead"])),
).await?;

use agentplane::model::fake::FakeProvider;

let provider = FakeProvider::new();
provider.will_say("approved");

// ... run, then assert on what the run did ...
assert_eq!(provider.calls(), 1, "replay must not ask the model again");

provider.streaming().will_say("approved");
// every scripted answer now arrives as text deltas and a usage snapshot
// before the completion returns