A2A Agents

Example agent implementations for the A2A Protocol with production-ready patterns and declarative configuration.

🚀 Quick Start (New Builder API)

Create a production-ready agent in just ~30 lines of code instead of ~300!

1. Define your agent (`agent.toml`)

[agent]
name = "My Agent"
description = "A helpful agent"

[[skills]]
id = "my_skill"
name = "My Skill"
description = "What this skill does"

2. Implement your handler

use a2a_rs::port::AsyncMessageHandler;
use async_trait::async_trait;

#[derive(Clone)]
struct MyHandler;

#[async_trait]
impl AsyncMessageHandler for MyHandler {
    async fn process_message(/* ... */) -> Result<Task, A2AError> {
        // Your business logic here
    }
}

3. Build and run!

use a2a_agents::AgentBuilder;
use a2a_rs::InMemoryTaskStorage;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    AgentBuilder::from_file("agent.toml")?
        .with_handler(MyHandler)
        .with_storage(InMemoryTaskStorage::new())
        .build()?
        .run()
        .await?;
    Ok(())
}

That's it! The framework handles servers, agent cards, authentication, and more.

📚 See complete Builder API documentation →

Overview

This crate provides two approaches for building agents:

✨ New: Declarative Builder API (Recommended)

90% less boilerplate - ~30 lines vs ~300 lines
TOML configuration - Define agents declaratively
Environment-aware - Built-in env var interpolation
Type-safe - Configuration validated at load time
Production-ready - Batteries included

Examples:

examples/minimal_agent.rs - Echo agent (~50 lines)
examples/reimbursement_builder.rs - Full-featured agent

Traditional Approach

The original hexagonal architecture approach with manual wiring:

Hexagonal Architecture: Clean separation between domain logic and adapters
Framework Integration: Uses DefaultRequestProcessor and storage backends
Protocol Compliance: Full A2A protocol support with HTTP transport
Modern Patterns: Async/await, builder patterns, and structured error handling

🔌 Model Context Protocol (MCP) Integration

You can expose any declarative A2A Agent as a Model Context Protocol (MCP) server over stdio transport. This allows MCP-compatible clients (like Claude Desktop) to invoke the agent's skills as local tools.

The bridge dispatches tool calls to the agent's message handler in-process, which means:

No backing HTTP server is required (you can set http_port = 0 for a pure-stdio server).
Authentication checks are bypassed for local stdio calls (secure by design as it is run locally by the client), while HTTP endpoints can still use standard Bearer/OAuth2 token auth.

1. Enable the MCP Server in `agent.toml`

Add the [features.mcp_server] section to your config:

[agent]
name = "My MCP Agent"
version = "1.0.0"

[server]
host = "127.0.0.1"
http_port = 0 # Can be 0 for pure-stdio mode

[features.mcp_server]
enabled = true
stdio = true
name = "Custom MCP Service Name"     # Optional override
version = "2.0.0"                    # Optional override

2. Run the MCP Agent

Compile and run your agent with the mcp-server Cargo feature enabled:

cargo run -p a2a-agents --features mcp-server --example mcp_server_agent

3. Claude Desktop Configuration

To connect Claude Desktop to your agent, add the following to your Claude Desktop configuration file (usually located at %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "a2a-echo-agent": {
      "command": "cargo",
      "args": [
        "run",
        "--release",
        "-p",
        "a2a-agents",
        "--features",
        "mcp-server",
        "--example",
        "mcp_server_agent"
      ]
    }
  }
}

Architecture

ReimbursementMessageHandler

The core business logic implementing AsyncMessageHandler:

Processes reimbursement requests using the A2A message format
Generates interactive forms for expense submissions
Validates and approves reimbursement requests
Returns structured responses with proper task states

ModernReimbursementServer

The server implementation using framework components:

Integrates with DefaultBusinessHandler for request processing
Uses InMemoryTaskStorage for task persistence
Configures SimpleAgentInfo with agent capabilities
Supports both HTTP transport

Usage

Quick Start - Unified Demo (Recommended)

Run the complete demo with both agent backend and web frontend in a single command:

# Run everything (agent backend + web UI)
cargo run --bin reimbursement_demo

# Open your browser to http://localhost:3000

This starts:

Agent Backend on http://localhost:8080 (HTTP)
Web Frontend on http://localhost:3000

The frontend automatically connects to the local agent and provides an interactive interface for submitting expenses and viewing tasks.

Advanced Usage

Run specific components:

# Run only the agent backend (HTTP)
cargo run --bin reimbursement_demo -- --mode agent

# Run only the web frontend (point it to an existing agent)
AGENT_HTTP_URL=http://localhost:8080 cargo run --bin reimbursement_demo -- --mode frontend

# Customize ports
cargo run --bin reimbursement_demo -- \
  --agent-http-port 8080 \
  --frontend-port 3000

# Run only HTTP transport for agent
cargo run --bin reimbursement_demo -- --transport http

Available Endpoints

Agent Backend:

HTTP API: http://localhost:8080 (ConnectRPC)
Agent Card: http://localhost:8080/agent-card

Web Frontend:

Main UI: http://localhost:3000
Task List: http://localhost:3000/tasks
Expense Form: http://localhost:3000/expense/new

Example Conversation

Here's an example conversation with the reimbursement agent:

User: "Can you reimburse me $50 for the team lunch yesterday?"

Agent: Returns a form

{
  "type": "form",
  "form": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "format": "date",
        "description": "Date of expense",
        "title": "Date"
      },
      "amount": {
        "type": "string",
        "format": "number",
        "description": "Amount of expense",
        "title": "Amount"
      },
      "purpose": {
        "type": "string",
        "description": "Purpose of expense",
        "title": "Purpose"
      },
      "request_id": {
        "type": "string",
        "description": "Request id",
        "title": "Request ID"
      }
    },
    "required": ["request_id", "date", "amount", "purpose"]
  },
  "form_data": {
    "request_id": "request_id_1234567",
    "date": "<transaction date>",
    "amount": "50",
    "purpose": " the team lunch yesterday"
  }
}

User: Submits the filled form

{
  "request_id": "request_id_1234567",
  "date": "2023-10-15",
  "amount": "50",
  "purpose": "team lunch with product team"
}

Agent: "Your reimbursement request has been approved. Request ID: request_id_1234567"

Current Limitations

This example implementation demonstrates the framework architecture but has simplified business logic:

Message Processing: Basic pattern matching instead of LLM integration
Storage: In-memory storage (framework supports SQLx for production)
Authentication: Not implemented (framework supports Bearer/OAuth2)
Form Processing: Simple JSON forms without complex validation

Future Enhancements

See TODO.md for the comprehensive modernization roadmap including:

Phase 2: Production features (SQLx storage, authentication)
Phase 3: AI/LLM integration for natural language processing
Phase 4: Additional agent examples (document analysis, research assistant)
Phase 5: Comprehensive testing and documentation
Phase 6: Docker support and production deployment

Framework Features Demonstrated

✅ AsyncMessageHandler trait implementation
✅ DefaultBusinessHandler integration
✅ InMemoryTaskStorage for task persistence
✅ SimpleAgentInfo for agent metadata
✅ HTTP transport support
✅ Structured error handling with A2AError
✅ Modern async/await patterns
✅ Builder patterns for complex objects

a2a-agents 0.3.0