RA2A

Comprehensive Rust SDK for the Agent2Agent (A2A) Protocol v1.0 — event-driven server, streaming client, gRPC transport, push notifications, and pluggable SQL task storage.

ra2a implements the full A2A v1.0 specification (released 2026-03-12) with an idiomatic Rust API. Functionally aligned with the official Go SDK — same protocol version, same type definitions, same error codes.

Features

• Three protocol bindings — JSON-RPC, HTTP+JSON/REST, and gRPC from the same AgentExecutor
• Composable server — Axum handlers you mount on your own router; you own the listener, TLS, and middleware
• Transport-agnostic client — ClientFactory auto-selects transport from AgentCard.supported_interfaces
• Streaming — SSE (message/stream, tasks/subscribe) with automatic non-streaming fallback
• Push notifications — webhook delivery with HMAC-SHA256 verification
• Pluggable storage — in-memory, PostgreSQL, MySQL, SQLite via sqlx
• Multi-tenancy — a2a_tenant_router with path-based tenant isolation
• Interceptors — CallInterceptor on both client and server for auth, telemetry, extension propagation
• Extension support — via companion crate ra2a-ext

Crates

Crate		Description
ra2a		Core SDK — types, client, server, gRPC, storage
ra2a-ext		Extensions — ExtensionActivator, ServerPropagator/ClientPropagator interceptors

Quick Start

Server

use std::{future::Future, pin::Pin};
use ra2a::{
    error::Result,
    server::{AgentExecutor, Event, EventQueue, RequestContext, ServerState, a2a_router},
    types::{
        AgentCard, AgentInterface, AgentSkill, Message, Part,
        Task, TaskState, TaskStatus, TransportProtocol,
    },
};

struct EchoAgent;

impl AgentExecutor for EchoAgent {
    fn execute<'a>(
        &'a self, ctx: &'a RequestContext, queue: &'a EventQueue,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'a>> {
        Box::pin(async move {
            let input = ctx.message.as_ref()
                .and_then(Message::text_content)
                .unwrap_or_default();
            let mut task = Task::new(&ctx.task_id, &ctx.context_id);
            task.status = TaskStatus::with_message(
                TaskState::Completed,
                Message::agent(vec![Part::text(format!("Echo: {input}"))]),
            );
            queue.send(Event::Task(task))?;
            Ok(())
        })
    }

    fn cancel<'a>(
        &'a self, ctx: &'a RequestContext, queue: &'a EventQueue,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'a>> {
        Box::pin(async move {
            let mut task = Task::new(&ctx.task_id, &ctx.context_id);
            task.status = TaskStatus::new(TaskState::Canceled);
            queue.send(Event::Task(task))?;
            Ok(())
        })
    }
}

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let mut card = AgentCard::new(
        "Echo Agent",
        "A simple echo agent.",
        vec![AgentInterface::new(
            "http://localhost:8080",
            TransportProtocol::new(TransportProtocol::JSONRPC),
        )],
    );
    card.skills.push(AgentSkill::new(
        "echo", "Echo", "Echoes user messages",
        vec!["echo".into(), "hello".into()],
    ));

    let state = ServerState::from_executor(EchoAgent, card);
    let app = axum::Router::new().merge(a2a_router(state));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
    axum::serve(listener, app).await
}

Client

use ra2a::client::Client;
use ra2a::types::{Message, Part, SendMessageRequest, SendMessageResponse};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_url("http://localhost:8080")?;

    let card = client.get_agent_card().await?;
    println!("Agent: {} — {}", card.name, card.description);

    let msg = Message::user(vec![Part::text("Hello!")]);
    let result = client.send_message(&SendMessageRequest::new(msg)).await?;

    match result {
        SendMessageResponse::Task(task) => {
            let reply = task.status.message.as_ref().and_then(|m| m.text_content());
            println!("[{:?}] {}", task.status.state, reply.unwrap_or_default());
        }
        SendMessageResponse::Message(msg) => {
            println!("{}", msg.text_content().unwrap_or_default());
        }
    }
    Ok(())
}

Feature Flags

A2A Protocol Reference

Protocol Operations

All 12 operations defined by the A2A v1.0 specification are implemented on both client and server. Method names follow PascalCase per the spec (§9.1):

Task Lifecycle

Submitted → Working → Completed
                    → Failed
                    → Canceled
                    → Rejected
           Input Required ←→ Working
           Auth Required  ←→ Working
Unknown (initial/query state)

Terminal states — Completed, Failed, Canceled, Rejected — end the task lifecycle. Interactive states — InputRequired, AuthRequired — resume to Working when the client responds.

Agent Discovery

Agents declare AgentInterface entries in their AgentCard, each specifying a URL, transport protocol (JSONRPC, GRPC, or HTTP+JSON), and protocol version. The card is published at /.well-known/agent-card.json and fetched automatically by the client. Agents may also expose an authenticated extended card via GetExtendedAgentCard.

Security Model

Push notifications use HMAC-SHA256 verification to authenticate webhook deliveries.

Security

This library has not been independently audited. See SECURITY.md for supported versions and vulnerability reporting.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project shall be dual-licensed as above, without any additional terms or conditions.

A QNTX open-source project.

Code is law. We write both.