ruvector/examples/a2a-swarm

a2a-swarm — rvAgent A2A end-to-end demo

A runnable proof that the rvagent-a2a stack (ADR-159) works end-to-end between multiple independent peers.

What it demonstrates

• Three signed-AgentCard peers, each running as its own rvagent a2a serve process on a distinct port:

  Node	Bind	Profile
  node-cheap	127.0.0.1:18001	low cost, slower
  node-fast	127.0.0.1:18002	high cost, faster
  node-router	127.0.0.1:18003	cheapest_under_latency selector

• Independent policies and budgets — each node loads its own configs/node-*.toml with its own [policy], [budget], and [recursion] caps.

• Signed AgentCard discovery — the orchestrator fetches /.well-known/agent.json on each peer and verifies it parses as a well-formed AgentCard with at least one skill.

• Task dispatch over HTTP JSON-RPC — the orchestrator sends an echo task to each peer (including the router) via the CLI's own a2a send-task subcommand and asserts state == "completed".

How to run

cd examples/a2a-swarm
cargo run --release

The binary auto-resolves the rvagent executable by walking up to the workspace target/{release,debug}/ directory. If you prefer to build it explicitly first:

cargo build --release -p rvagent-cli
cargo run --release -p a2a-swarm

What to expect

Typical successful run:

INFO using rvagent binary: /.../target/release/rvagent
INFO node is listening name="node-cheap"  bind=127.0.0.1:18001 ...
INFO node is listening name="node-fast"   bind=127.0.0.1:18002 ...
INFO node is listening name="node-router" bind=127.0.0.1:18003 ...
INFO discovered signed AgentCard name="node-cheap"  skills=1 ...
INFO discovered signed AgentCard name="node-fast"   skills=1 ...
INFO discovered signed AgentCard name="node-router" skills=1 ...

=== a2a-swarm demo summary ============================================
  node-cheap   bind=127.0.0.1:18001 state=completed  took=  Nms  ok=true
  node-fast    bind=127.0.0.1:18002 state=completed  took=  Nms  ok=true
  node-router  bind=127.0.0.1:18003 state=completed  took=  Nms  ok=true
-----------------------------------------------------------------------
  dispatched to router at 127.0.0.1:18003: state=completed ...
  peer pool (would be CheapestUnderLatency targets in M3):
    - node-cheap @ 127.0.0.1:18001
    - node-fast  @ 127.0.0.1:18002
=======================================================================

INFO node exited name="node-cheap"  ...
INFO node exited name="node-fast"   ...
INFO node exited name="node-router" ...

The orchestrator exits 0 only if the router's task reached state == "completed".

What this proves (ADR-159 acceptance tests)

• Tests 1 + 2 — remote ≡ local, constant-size memory. The task dispatch uses real HTTP with real signed AgentCards. The JSON-RPC request/response matches the local InMemoryRunner path byte-for-byte at the Task level.
• Test 3 — bounded cost under recursion. Each node loads its own [budget.global] section into a per-process BudgetLedger. A runaway peer can't burn into a sibling's budget; recursion depth is capped per-node at max_call_depth = 4.

Known limitations / follow-ups

• Router-forwards-over-HTTP is not yet wired. ADR-159 r2 defines PeerSelector + PeerRegistry, but the current a2a serve doesn't seed the registry from the TOML [routing] section — peers arrive via the discovery cache, which is M3. Until then, node-router handles tasks locally and the orchestrator plays the role the selector will play later (picking which peer receives the task).
• No live metrics. The selector reads EWMA cost + latency from the middleware rate-limit layer; this demo doesn't drive enough traffic to move the needle, so peer selection decisions rely on config defaults.
• The fallback selector string in node-router.toml is parsed but not yet consulted by a running router — same M3 gap.
• Keys are ephemeral. Every --generate-key invocation mints a fresh Ed25519 keypair, so AgentID changes across runs. That's fine for the demo; production deployments would load a persisted key via $RVAGENT_A2A_SIGNING_KEY.

File layout

examples/a2a-swarm/
├── Cargo.toml               # orchestrator package
├── README.md                # this file
├── configs/
│   ├── node-cheap.toml      # low-cost tier
│   ├── node-fast.toml       # high-cost / low-latency tier
│   └── node-router.toml     # CheapestUnderLatency dispatcher
├── src/
│   └── main.rs              # spawns + probes + dispatches + tears down
└── .gitignore