Pure Rust implementation of the Agent2Agent (A2A) protocol, written against the v1.0.1 wire specification — the open, vendor-neutral standard for AI-agent interoperability.

Build, connect, and orchestrate AI agents with a type-safe, async-first SDK spanning four transports — JSON-RPC 2.0, REST, WebSocket, and gRPC — for both client and server.

The A2A protocol was originally developed by Google and donated to the Linux Foundation in June 2025. The A2A project maintains its own official SDKs and publishes the specification and conformance suite this implementation is measured against.

This is an independent project. It is not affiliated with, endorsed by, or governed by the A2A project, the Linux Foundation, or Google, and it is not an official SDK. It tracks the published v1.0.1 specification (released 2026-05-28); the protocol version on the wire remains 1.0, because §3.6 keeps patch numbers out of requests, responses and Agent Cards. It is graded against the A2A project's official Technology Compatibility Kit; where it falls short of that suite, docs/official-tck-findings.md records exactly where and why.

a2a-protocol-client and a2a-protocol-server are siblings — neither depends on the other. Use only what you need.

a2a-protocol-slimrpc sits outside the workspace with its own lockfile, because agntcy-slim-rpc brings 379 transitive dependencies (including a native C crypto build) against 12 for a2a-protocol-types. None of that reaches the four crates above, which do not depend on it. It is versioned independently and is currently on the 0.5 line — bindings/a2a-protocol-slimrpc/Cargo.toml is the authority for its exact version — see the book chapter for why, and for the version-coupling rule that independence does not remove.

[dependencies]
a2a-protocol-sdk = "0.13"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

use a2a_protocol_sdk::prelude::*;

struct MyAgent;

// The agent_executor! macro eliminates Pin<Box<dyn Future>> boilerplate
agent_executor!(MyAgent, |ctx, queue| async {
    let emit = EventEmitter::new(ctx, queue);

    emit.status(TaskState::Working).await?;
    emit.artifact("result", vec![Part::text("Hello from my agent!")], None, Some(true)).await?;
    emit.status(TaskState::Completed).await?;

    Ok(())
});

Note: AgentExecutor is object-safe — methods return Pin<Box<dyn Future>>. This means RequestHandler, RestDispatcher, and JsonRpcDispatcher are not generic; they store the executor as Arc<dyn AgentExecutor> for easy composition.

use std::sync::Arc;
use a2a_protocol_sdk::prelude::*;

let handler = Arc::new(
    RequestHandlerBuilder::new(MyAgent)
        .with_agent_card(agent_card)
        .build()
        .expect("build handler"),
);

// One-liner server startup (replaces ~25 lines of hyper boilerplate)
serve("0.0.0.0:3000", JsonRpcDispatcher::new(handler)).await?;

use a2a_protocol_sdk::prelude::*;

let client = ClientBuilder::new("http://localhost:8080")
    .with_retry_policy(RetryPolicy::default())  // automatic retry on transient errors
    .build()
    .expect("build client");

// Synchronous request
let response = client
    .send_message(params)
    .await
    .expect("send_message");

// Streaming request
let mut stream = client
    .stream_message(params)
    .await
    .expect("stream_message");

while let Some(event) = stream.next().await {
    match event? {
        StreamResponse::StatusUpdate(ev) => println!("Status: {:?}", ev.status.state),
        StreamResponse::ArtifactUpdate(ev) => println!("Artifact: {}", ev.artifact.id),
        StreamResponse::Task(task) => println!("Task: {}", task.id),
        StreamResponse::Message(msg) => println!("Message: {:?}", msg),
        // StreamResponse is #[non_exhaustive] — always keep a catch-all.
        _ => {}
    }
}

The hands-on answer to "how is an agent different from a wrapped prompt?": three cooperating agents triage a production incident — a vague alert parks the task in INPUT_REQUIRED, the operator's answer resumes the same task, the orchestrator delegates to a deterministic log-search agent and an LLM-backed runbook agent over real A2A calls, progress streams live, the incident report lands as an artifact, and a parked task can be cancelled. Runs fully local with Qwen3.5-0.8B (a ~500 MB Apache-2.0 model, via llama-server or Ollama) or with no model at all:

cargo run -p incident-response

A 4-agent team that exercises the SDK broadly — 102 end-to-end tests on the default feature set, which already enables WebSocket, gRPC, Axum, SQLite, signing and OTel (87 with --no-default-features; both figures are what cargo run -p agent-team prints) covering all four transports (JSON-RPC, REST, WebSocket, gRPC), streaming, push notifications, agent-to-agent orchestration, cancellation, concurrency stress, multi-tenancy, large payloads, metrics, SDK regression testing, batch JSON-RPC, auth rejection, extended/dynamic agent cards, HTTP caching, backpressure, agent card signing, Axum framework integration, and SQLite-backed stores:

cargo run -p agent-team

# With all optional features
cargo run -p agent-team --features grpc,websocket,axum,sqlite,signing,otel

The whole SDK in one screen — 35 lines, one dependency (a2a-protocol-sdk), no feature flags. It greets whoever sends it a message:

cargo run -p hello-agent

curl -X POST http://127.0.0.1:3000 \
  -H 'content-type: application/json' -H 'A2A-Version: 1.0' \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{
        "message":{"messageId":"m1","role":"ROLE_USER","parts":[{"text":"Tom"}]}}}'

It doubles as the regression test for the Quick Start above: it depends on exactly what the Quick Start tells you to depend on, so if that snippet stops compiling, cargo build -p hello-agent fails with it.

cargo run -p deploy-agent
docker build -f examples/deploy-agent/Dockerfile -t deploy-agent .
kubectl apply -f examples/deploy-agent/deployment.yaml

hello-agent is the smallest agent that answers A2A; this is the smallest one you can ship. Environment configuration, /healthz and /readyz, SIGTERM draining, a 0.0.0.0 bind, a two-stage container and a Kubernetes manifest whose probes point at those endpoints. Its sharpest test asserts the agent card advertises the public URL and never leaks the bind address — the deployment bug whose only symptom is clients failing to call back. See examples/deploy-agent.

A minimal example demonstrating both JSON-RPC and REST transports with synchronous and streaming modes:

cargo run -p echo-agent

A Rust coordinator agent that delegates to worker agents written in Python, JavaScript, Go, and Java — proving cross-language A2A interoperability:

# Start the ITK worker agents first (see itk/README.md), then:
cargo run -p multi-lang-team

Real LLM agents behind the A2A protocol — both pass the in-repo TCK (JSON-RPC binding: 21/21 graded, 1 N/A, gated on every push and pull request by tck.yml's tck-example-agents job) and run against hosted providers or any local OpenAI-compatible server, with honest failure semantics (provider errors fail the task; they are never disguised as successful artifacts):

# rig AI framework (https://github.com/0xPlaygrounds/rig)
OPENAI_API_KEY=sk-... cargo run -p rig-a2a-agent

# genai multi-provider LLM client (https://crates.io/crates/genai)
GENAI_MODEL=gpt-4o-mini cargo run -p genai-a2a-agent

A standalone conformance test runner that validates any A2A server against the protocol spec over the JSON-RPC and REST bindings (the gRPC and WebSocket transports are covered by the agent-team E2E tests instead):

# Test a local server
cargo run -p a2a-tck -- --url http://localhost:8080 --binding jsonrpc

# Run the full cross-language ITK (requires Docker)
docker compose -f itk/docker-compose.yml up --build --abort-on-container-exit

a2a is a command-line client over a2a-protocol-client: fetch a card, send or stream a message, get, cancel and list tasks, all as JSON, over any of the four bindings. It is unpublished — a publish = false workspace member, built from this repository, not on crates.io:

cargo run -p a2a-cli -- card http://127.0.0.1:3111
cargo run -p a2a-cli -- send http://127.0.0.1:3111 "hello"
cargo run -p a2a-cli -- stream http://127.0.0.1:3111 "hello"

Commands, flags, a captured transcript and the exit-code table are in tools/a2a-cli/README.md.

┌────────────────────────────────────────────┐
│  Your Code                                 │
│  implements AgentExecutor or uses Client   │
└─────────────────────┬──────────────────────┘
                      │
┌─────────────────────▼──────────────────────┐
│  a2a-protocol-server / a2a-protocol-client │
│ RequestHandler · AgentExecutor · A2aClient │
└─────────────────────┬──────────────────────┘
                      │
┌─────────────────────▼──────────────────────┐
│  Transport Layer                           │
│  JsonRpcDispatcher · RestDispatcher        │
│  A2aRouter (axum, feature-gated)           │
│  WebSocketDispatcher (feature-gated)       │
│  GrpcDispatcher (feature-gated)            │
│  JsonRpcTransport · RestTransport          │
│  WebSocketTransport (feature-gated)        │
│  GrpcTransport (feature-gated)             │
└─────────────────────┬──────────────────────┘
                      │
┌─────────────────────▼──────────────────────┐
│  hyper 1.x · HTTP/1.1 + HTTP/2             │
└────────────────────────────────────────────┘

The server uses a 3-layer architecture:

1. You implement AgentExecutor — your agent logic, produces events via EventQueueWriter
2. RequestHandler orchestrates — manages tasks, stores, push notifications, interceptors
3. Dispatchers handle HTTP/gRPC — JsonRpcDispatcher (JSON-RPC 2.0), RestDispatcher (REST), A2aRouter (Axum), WebSocketDispatcher (WebSocket), and GrpcDispatcher (gRPC) wire hyper/tonic/axum to the handler

# Run the test suite (3,601 passing with --all-features, measured 2026-09-20:
# 3,425 unit and integration tests plus 176 doctests. 199 more are #[ignore]d
# behind a live database and run in CI's postgres job. CI's `test` job runs
# fourteen feature combinations per matrix cell)
cargo test --workspace --all-features

# Run the end-to-end example
cargo run -p echo-agent

# Lint and format checks
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check

# Build documentation
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps

# Run benchmarks (Criterion suites ×15 — transport, protocol,
# lifecycle, concurrency, cross-language, realistic, error paths, backpressure,
# data volume, memory, enterprise, production, advanced scenarios,
# coordinator chain under fault, and send latency breakdown — the coordinator
# chain is the only agent-level one,
# see book/src/reference/benchmarks.md for caveats on how to read it)
cargo bench -p a2a-benchmarks

# Mutation testing (requires cargo-mutants and cargo-nextest).
# --test-tool=nextest is not optional: .config/nextest.toml supplies the
# per-test kill that stops a hung mutant reporting TIMEOUT instead of caught.
# See book/src/deployment/testing.md for the full CI invocation.
cargo mutants --workspace --test-tool=nextest -- --all-features

# Fuzz JSON deserialization (requires nightly)
cd fuzz && cargo +nightly fuzz run json_deser

Published as 0.x. All 11 A2A methods are implemented across the four transports, alongside HTTP caching, agent-card signing, optional tracing and OpenTelemetry, TLS, and the request-hardening features listed above. The API is still stabilizing — minor versions may carry breaking changes, as described under Stability. docs/implementation/plan.md covers the implementation history and beyond-spec extensions.

Against the A2A project's official Technology Compatibility Kit, 88 of 114 MUST requirements pass and 4 fail (re-measured 2026-09-01 against a2a-tck@de6af18). All four failures are the same cause, and it is not a deviation from the specification: the suite grades §5.4's error-mapping table against the copy of the specification it vendors, which its own specification/version.json records as A2A v1.0.0, taken 2026-03-13. A2A released v1.0.1 on 2026-05-28, which rewrote six of that table's nine rows. Each of the four fails on exactly the one binding whose cell the two copies disagree about and passes on the bindings where they agree; this SDK answers what the published table says, as does the official Python SDK. They are baselined in tck/conformance-baseline.json with the evidence in §20 and §21, and they clear when the suite refreshes its copy — reported upstream as a2aproject/a2a-tck#231. Of the remaining 22, 21 have no test function in the upstream suite and one (CARD-EXT-002) is structurally inapplicable — so they are unmeasured rather than passing. docs/official-tck-findings.md has the per-requirement breakdown and reproduction steps; §16 accounts for the 21 family by family — six the upstream suite tags unautomatable, two it has ruled out of scope, and thirteen open backlog items in its own tracker — and shows why none can be closed from this repository.

ROADMAP.md is the honest counterpart to this section: it records where this project's own gates do not yet measure everything they appear to, which conformance claims rest on the in-repo runner rather than the official suite, and which questions are still undecided. Worth reading before depending on this SDK for anything load-bearing.

All crates follow Semantic Versioning 2.0.0. During the 0.x series, minor versions may include breaking changes as the API stabilizes. Since 2026-09-09 that is governed by STABILITY.md: deprecate for at least one minor release before removing, batch breaking changes into at most one minor release per month, label them under a ### Breaking heading, and prove compatibility with cargo-semver-checks on every pull request. It also states what is designed to stay compatible and the criteria for 1.0.

The server crate's twelve public traits — AgentExecutor, TaskStore, PushConfigStore, PushSender, ServerInterceptor, TenantResolver, Metrics, Dispatcher, AgentCardProducer, RateLimitCounter, and the two event-queue traits — are unsealed and will stay that way: they are the extension points a deployment substitutes its own infrastructure into, and the out-of-workspace a2a-protocol-slimrpc binding exists only because they are open. New trait methods are always added with defaults so external implementations keep compiling; the rules maintainers follow when doing so — including why a defaulted method is not free — are in CONTRIBUTING.md. Protocol enums and key structs that can grow with the A2A specification are marked #[non_exhaustive] to allow forward-compatible additions in patch releases; the three deliberate exceptions are closed sets fixed by their underlying standards (ApiKeyLocation — OpenAPI's header/query/cookie; JsonRpcResponse — JSON-RPC 2.0's result/error; and JsonRpcRequestId — JSON-RPC 2.0's absent/null/value id states), which stay exhaustive so consumers can match them completely.

Rust 1.88 or later (stable), edition 2024.

Policy. The MSRV is treated as part of the public API: raising it is a minor version bump, never a patch, and the release notes say so. It is raised only when a language or standard-library feature earns it — not incidentally, because a transitive dependency moved. The edition-2024 resolver selects dependency versions compatible with the declared rust-version, and CI builds and tests the workspace on exactly that toolchain. The full policy is in STABILITY.md.

History. The floor was 1.93 until 2026-09-09, when it was lowered to 1.88 — the workspace had never needed anything newer, and 1.88 is the oldest toolchain the current dependency tree (time, serde_with, darling) declares support for. Lowering it further would mean holding those crates at older releases, a cost weighed against the adoption benefit on the roadmap.

Contributions are welcome — see CONTRIBUTING.md for coding standards, testing requirements, and quality gates, and GOVERNANCE.md for how decisions get made. Participation is governed by the Code of Conduct (Contributor Covenant 2.1).

ROADMAP.md lists what is committed for upcoming releases, alongside the verification gaps and open questions noted under Project Status.

Every commit must be signed off under the Developer Certificate of Origin (git commit -s) by a human git author; CI enforces this. PROVENANCE.md documents this project's use of AI coding assistants, the provenance of third-party material in the tree, and the blanket DCO certification covering commits made before the DCO was adopted.

To report a security vulnerability, follow SECURITY.md — not the public issue tracker.

Apache-2.0 — see LICENSE, and NOTICE for the project's copyright notice and third-party attributions.