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:

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

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 and WebSocket transports

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) and ws://localhost:8081 (WebSocket)
• 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 + WebSocket)

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 \

  --agent-ws-port 8081 \

  --frontend-port 3000


# Run only HTTP transport for agent

cargo run --bin reimbursement_demo -- --transport http


# Enable WebSocket support in frontend

cargo run --bin reimbursement_demo -- --frontend-use-websocket

Available Endpoints

Agent Backend:

• HTTP API: http://localhost:8080 (JSON-RPC)
• WebSocket: ws://localhost:8081
• 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:

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

2. 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"
     }
   }
   

3. User: Submits the filled form

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

4. 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:

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

Framework Features Demonstrated

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