a2a-temporal

Durable A2A task bridge backed by Temporal workflow templates.

a2a-temporal is an early-stage bridge that makes A2A tasks durable without inventing a new workflow VM. V1 focuses on a small, production-shaped core: JSON-RPC A2A requests, explicit idempotency, Temporal workflow templates, a Bridge Store read/idempotency model, artifact handles, and scoped conformance tests.

A2A client submits task
        ↓
a2a-temporal validates identity, contract, and idempotency key
        ↓
Temporal runs a versioned Go workflow template
        ↓
worker calls downstream A2A agents through activities
        ↓
Bridge Store records idempotency, snapshots, events, and artifact metadata
        ↓
A2A client reads truthful task state and terminal result

Status

🚧 Early development. Milestones 1 and 2 are implemented as local/demo paths: a JSON-RPC A2A bridge reserves tasks in SQLite, starts a Temporal workflow, calls deterministic mock A2A reviewers, and returns a terminal review_bundle_v1 artifact. The M2 smoke covers three configured branches plus optional-branch degradation.

V1 Scope

• Workflow templates, not a VM: contracts configure known Go/Temporal templates; no generic interpreter in V1.
• Durability: Temporal owns workflow execution, retries, timers, signals, and cancellation.
• Bridge Store: Postgres/SQLite store for idempotency reservations, signal dedupe, latest task snapshots, bounded events, and artifact metadata.
• Idempotency: production mutations require stable idempotency keys.
• Human input: approval gates map A2A input-required to Temporal signals.
• Multi-agent calls: bounded fan-out to configured downstream A2A agents.
• Artifacts: large/sensitive outputs stay out of Temporal history and are exposed through authenticated handles.
• Conformance reports: scoped test evidence, not public claims of proof or certification.

Development

Canonical environment: flake.nix. Canonical commands: Justfile. Optional auto-loading: .envrc via direnv allow.

# Enter the pinned Nix development shell
nix develop

# See available project commands
just --list

# Run unit tests
just test

# Run UBS static bug scan for Go code
just ubs-ci

# Start a local Temporal dev server, probe it, and stop it
just smoke-temporal-cli

# Run the full local Milestone 1 demo smoke test
just smoke-m1-temporal

# Run the mock-only Milestone 2 parallel demo smoke test
just smoke-m2-parallel

# Start a recording-friendly mock-only M2 stack until Ctrl-C
just demo-m2-recording

# Submit one task to that running recording stack
just demo-m2-client

See docs/TESTING.md for the test matrix, CI behavior, UBS status, smoke coverage, and future M4 scenarios.

Milestone 1 Demo

just smoke-m1-temporal starts an isolated local Temporal dev server, Bridge API, Temporal worker, and mock reviewer agent. The smoke client submits an A2A SendMessage request with an idempotency key, polls GetTask until completion, prints the terminal review_bundle_v1 artifact, verifies duplicate same-key/same-body replay, and verifies same-key/different-body rejection.

Milestone 2 Parallel Demo

just smoke-m2-parallel starts the same local Temporal/Bridge/worker stack with two deterministic mock reviewer agents: one success mock and one permanent-failure mock used only by the optional ops branch. It runs two smoke profiles:

• m2-success: selects the 2.0.0-demo three-branch contract from the Agent Card and verifies terminal completed, degraded=false, and one bundle entry each for security, privacy, and ops.
• m2-optional-failure: selects the 2.0.1-demo three-branch contract and verifies terminal completed, degraded=true, required branch success, and a safe optional ops branch error.

The smoke output prints the selected contract hash, task ID, observed state transitions, terminal degraded flag, branch summaries, and the complete review_bundle_v1 artifact. The M1 and M2 recipes use the same fixed local demo ports, so run them one at a time.

Recording Flow

For a portfolio recording, run nix develop -c just smoke-m2-parallel first to show the deterministic mock-only proof, including the optional-failure degraded case. For an interactive take, run nix develop -c just demo-m2-recording; it keeps local Temporal, the Bridge API, the worker, and a mock reviewer running until Ctrl-C and prints the A2A endpoint, Agent Card URL, and Temporal UI URL.

With demo-m2-recording still running, either run nix develop -c just demo-m2-client to submit one CLI task, or connect an A2A client such as OpenClaw to http://127.0.0.1:9999/.well-known/agent-card.json. Submit a vendor review prompt such as Review Acme Vendor for security, privacy, and operational risk., then show the task moving through submitted, working, and terminal completed with the three branch bundle. Temporal UI is available on http://127.0.0.1:8233.

The demo claim is intentionally narrow: durable parent A2A task orchestration backed by Temporal, with idempotent local demo agents and truthful task snapshots. It does not claim production readiness, certification, conformance, or production-grade exactly-once downstream execution for arbitrary external agents. The public Agent Card extension marks the default mode as local/mock-only and real external agent execution as disabled by default. External bindings remain disabled-by-default future work unless their idempotency behavior is separately verified.

Architecture

See docs/SPEC.md for the current bridge design, milestone plan, A2A/Temporal mapping, Bridge Store rules, idempotency behavior, conformance model, and acceptance tests.

Related

• a2a-adapter — A2A bridge for local agent backends
• a2a-go — Official A2A Go SDK
• Temporal — Durable execution platform

License

Apache 2.0