Crate a2a_agents 

A2A Agents - Framework for building A2A Protocol agents

This crate provides a declarative, configuration-driven framework for building agents that implement the A2A Protocol v1.0.0.

Architecture

The crate is organized into three main layers:

• Core Framework (core) - Builder, configuration, and runtime
• Plugin System (traits) - Traits for extending agent functionality
• Utilities (utils) - Common helpers for agent development
• Example Agents (agents) - Reference implementations

Quick Start

use a2a_agents::core::AgentBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    AgentBuilder::from_file("config.toml")?
        .with_handler(my_handler)
        .build_with_auto_storage()
        .await?
        .run()
        .await?;
    Ok(())
}

Core Framework

The core framework provides the essential building blocks:

• AgentBuilder - Fluent API for agent construction
• AgentConfig - TOML-based configuration
• AgentServer - Per-agent serving lifecycle
• AgentRuntime - Fleet supervision (provision/start/stop/health)

Plugin System

Implement the AgentPlugin trait to create agents that integrate seamlessly with the framework:

use a2a_agents::traits::{AgentPlugin, SkillDefinition};
use a2a_rs::port::{AsyncMessageHandler, RequestContext};
use a2a_rs::domain::{A2AError, Message, Task};
use async_trait::async_trait;

#[derive(Clone)]
struct MyAgent;

impl AgentPlugin for MyAgent {
    fn name(&self) -> &str { "My Agent" }
    fn description(&self) -> &str { "An example agent" }
    fn skills(&self) -> Vec<SkillDefinition> { vec![] }
}

#[async_trait]
impl AsyncMessageHandler for MyAgent {
    async fn process_message(
        &self,
        _task_id: &str,
        _message: &Message,
        _ctx: &RequestContext,
    ) -> Result<Task, A2AError> {
        todo!()
    }
}

Features

• default - What the a2a CLI needs: llm, mcp-server, schema, sqlx
• llm - Generic config-driven LLM handler and its tool-calling loop
• mcp-server - Expose a configured agent as an MCP server; MCP tool sources
• mcp-client - Call out to external MCP servers from an agent
• schema - JSON Schema export for AgentConfig (a2a print-schema)
• sqlx - Enable SQLx-based task storage
• auth - Enable authentication features (JWT, OAuth2)
• reimbursement-agent - Build the reimbursement sample agent (opt-in)
• ap2 - Agent Payments Protocol types

Library-only consumers can take default-features = false and enable just what they use; the defaults exist so cargo install a2a-agents yields a working a2a binary.

Re-exports

pub use core::AgentBuilder;

pub use core::AgentConfig;

pub use core::AgentServer;

pub use core::BuildError;

pub use core::ConfigError;

pub use core::ServerError;

pub use traits::AgentPlugin;

pub use traits::SkillDefinition;

pub use handlers::tools::A2aAgentToolSource;

pub use handlers::tools::ConnectedPeer;

pub use handlers::tools::PeerResolver;

pub use handlers::tools::PeerUnavailable;

pub use handlers::tools::ToolSource;

pub use registry::AgentId;

pub use registry::AgentRegistry;

pub use registry::CardRefresher;

pub use registry::CardSource;

pub use registry::CardSourceError;

pub use registry::DEFAULT_REFRESH_INTERVAL;

pub use registry::DiscoveredPeer;

pub use registry::HttpCardSource;

pub use registry::InMemoryAgentRegistry;

pub use registry::InMemoryCardSource;

pub use registry::Liveness;

pub use registry::RefreshReport;

pub use registry::RegisteredAgent;

pub use registry::RegistryError;

pub use runtime::AgentRuntime;

pub use runtime::AgentSpec;

pub use runtime::ContainerHardening;

pub use runtime::ContainerRuntime;

pub use runtime::EnvAllowlist;

pub use runtime::InMemoryAgentRuntime;

pub use runtime::LocalProcessRuntime;

pub use runtime::Recovered;

pub use runtime::RuntimeError;

pub use runtime::RuntimeHealth;

pub use runtime::RuntimeStatus;

pub use control_plane::AgentLogs;

pub use control_plane::AgentStatus;

pub use control_plane::ControlPlane;

pub use control_plane::ControlPlaneAuth;

pub use control_plane::ControlPlaneClient;

pub use control_plane::ControlPlaneClientError;

pub use control_plane::ControlPlaneError;

pub use control_plane::DeployedAgent;

pub use control_plane::ListFilter;

pub use control_plane::control_plane_router;

pub use handlers::llm::LlmHandler;

pub use handlers::tools::McpToolSource;

pub use handlers::tools::UnusedInner;

pub use agents::reimbursement::ReimbursementHandler;

Modules

agents

Example agent implementations.

control_plane

Control plane — compose runtime + registry into a deployable platform with an HTTP API. Control plane — compose the runtime, registry, and card-source ports into a platform.

core

Core framework infrastructure for building A2A agents.

handlers

Generic config-driven handlers. Generic config-driven handlers.

registry

Agent registry / discovery — find peers by skill instead of hard-coded URLs. Agent registry / discovery.

runtime

Agent runtime — run agents as managed, isolatable units (provision/start/stop/health). Agent runtime — a place to run agents as managed, isolatable units.

traits

Plugin traits for extending agent functionality.

utils

Utility modules for agent development.