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 protocol specification v1.0 with an idiomatic Rust API, providing a Client → Transport → AgentCard discovery flow on the client side and an AgentExecutor → EventQueue → RequestHandler pipeline on the server side. It is functionally aligned with the official Go SDK — same protocol version, same 12 JSON-RPC methods, same type definitions, same error codes.

Crates

Crate		Description
ra2a		SDK — Client, Server, Types, gRPC, task storage
ra2a-ext		Extensions — extension activator, metadata propagator interceptors

Quick Start

Server

The SDK provides composable Axum handlers — you own the router, listener, TLS, and middleware.

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(ra2a::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(())
}

Architecture

ra2a crate

ra2a-ext crate

Feature Flags

Proto Source

The protobuf definition (a2a.proto) is sourced directly from the official A2A repository via git submodule, pinned to the v1.0.0 tag. The googleapis dependency is also vendored as a submodule.

After cloning, initialize both submodules:

git submodule update --init --recursive

To upgrade the proto to a new release:

git -C ra2a/proto/a2a checkout <new-tag>
git add ra2a/proto/a2a
git commit -m "build(proto): bump A2A proto to <new-tag>"

A2A Protocol Overview

Protocol Version

ra2a targets A2A v1.0 (released 2026-03-12). The a2a.proto is the normative source for the protocol data model; JSON-RPC and gRPC are separate protocol bindings derived from it.

JSON-RPC Methods

All 12 methods defined by the A2A specification are implemented on both client and server:

Task Lifecycle

Tasks progress through well-defined states with terminal conditions:

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. InputRequired and AuthRequired are interactive states that resume to Working when the client responds.

Agent Discovery

Agents declare one or more 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. The client's card resolver fetches and caches it automatically. Agents may also expose an authenticated extended card via agent/getAuthenticatedExtendedCard for capabilities that require authorization to discover.

Security Model

A2A supports five security scheme types in the AgentCard:

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

Security

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

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.