a2a-server 0.1.0

In‑memory FSM for the A2A Protocol with Pydantic v2 models

A2A: Agent-to-Agent Communication Server

A lightweight, transport-agnostic framework for agent-to-agent communication based on JSON-RPC, implementing the A2A Protocol.

Server

The A2A server provides a flexible JSON-RPC interface for agent-to-agent communication with support for multiple transport protocols.

Features

• Multiple Transport Protocols:

  • HTTP JSON-RPC endpoint (POST /rpc)
  • WebSocket for bidirectional communication (/ws)
  • Server-Sent Events (SSE) for real-time updates (/events)
  • Standard I/O mode for CLI applications (--stdio)

• Task-Based Workflow:

  • Create and manage asynchronous tasks
  • Monitor task status through state transitions
  • Receive artifacts produced during task execution

• Simple Event System:

  • Real-time notifications for status changes
  • Artifact update events
  • Event replay for reconnecting clients

• Extensible Handler System:

  • Automatic handler discovery
  • Plugin system via entry points (a2a.task_handlers)
  • Custom handler development via subclassing TaskHandler

• Intuitive URL Structure:

  • Direct handler mounting at /{handler_name}/rpc, /{handler_name}/ws, and /{handler_name}/events
  • Default handler accessible at root paths (/rpc, /ws, /events)
  • Handler health checks at /{handler_name}

• A2A Protocol Compliant:

  • Agent Cards at /.well-known/agent.json and /{handler_name}/.well-known/agent.json
  • Standard Task/Message/Artifact structure
  • Streaming support

Running the Server

# Basic usage (HTTP, WS, SSE on port 8000)
uv run a2a-server

# Specify host and port
uv run a2a-server --host 0.0.0.0 --port 8000

# Enable detailed logging
uv run a2a-server --log-level debug

# Run in stdio JSON-RPC mode
uv run a2a-server --stdio

# List all available task handlers
uv run a2a-server --list-handlers

# List all registered routes (useful for debugging)
uv run a2a-server --list-routes

# Register additional handler packages
uv run a2a-server --handler-package my_custom_module.handlers

# Disable automatic handler discovery
uv run a2a-server --no-discovery

Example: Configuring Agents via YAML

You can configure multiple agents with their capabilities and agent cards in YAML:

server:
  port: 8000

handlers:
  use_discovery: false
  default: chef_agent

  pirate_agent:
    type: a2a_server.tasks.handlers.google_adk_handler.GoogleADKHandler
    agent: a2a_server.sample_agents.pirate_agent.pirate_agent
    name: pirate_agent
    agent_card:
      name: Pirate Agent
      description: "Converts your text into salty pirate‑speak"
      url: "https://pirate.example.com"
      version: "0.1.0"
      documentationUrl: "https://pirate.example.com/docs"
      provider:
        organization: "Acme"
        url: "https://acme.example.com"
      capabilities:
        streaming: true
        pushNotifications: false
      authentication:
        schemes:
          - "Bearer"
      defaultInputModes:
        - "text/plain"
      defaultOutputModes:
        - "text/plain"
      skills:
        - id: pirate-talk
          name: Pirate Talk
          description: "Turn any message into pirate lingo"
          tags:
            - pirate
            - fun
          examples:
            - "Arrr! Give me yer loot!"

  chef_agent:
    type: a2a_server.tasks.handlers.google_adk_handler.GoogleADKHandler
    agent: a2a_server.sample_agents.chef_agent.chef_agent
    name: chef_agent
    agent_card:
      name: Chef Agent
      description: "Suggests delicious recipes from your ingredients"
      # Other fields can be automatically derived...

Then launch:

uv run a2a-server --config agent.yaml --log-level debug

Interacting with the Server

# Create a task with default handler
curl -N -X POST http://127.0.0.1:8000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tasks/send",
    "params":{
      "message":{
        "role":"user",
        "parts":[{ "type":"text","text":"What can I make with chicken?" }]
      }
    }
  }'

# Create a task with specific handler
curl -N -X POST http://127.0.0.1:8000/pirate_agent/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tasks/send",
    "params":{
      "message":{
        "role":"user",
        "parts":[{ "type":"text","text":"Tell me about the sea" }]
      }
    }
  }'

# Stream events from default handler
curl -N http://127.0.0.1:8000/events

# Stream events from specific handler
curl -N http://127.0.0.1:8000/pirate_agent/events

# Get the default agent card (A2A Protocol compliant)
curl http://127.0.0.1:8000/.well-known/agent.json

# Get a specific handler's agent card
curl http://127.0.0.1:8000/pirate_agent/.well-known/agent.json

# Check handler health
curl http://127.0.0.1:8000/pirate_agent

URL Structure

The server provides a consistent URL structure:

Default Handler

• /rpc - JSON-RPC endpoint for the default handler
• /ws - WebSocket endpoint for the default handler
• /events - SSE endpoint for the default handler
• /.well-known/agent.json - Agent Card for the default handler (A2A Protocol compliant)

Specific Handlers

• /{handler_name}/rpc - JSON-RPC endpoint for a specific handler
• /{handler_name}/ws - WebSocket endpoint for a specific handler
• /{handler_name}/events - SSE endpoint for a specific handler
• /{handler_name}/.well-known/agent.json - Agent Card for a specific handler (A2A Protocol compliant)

Health Checks

• / - Root health check with information about all handlers
• /{handler_name} - Handler-specific health check

Agent Cards

The server implements the A2A Protocol's Agent Card specification. Agent cards contain information about the agent's:

• Name, description, and version
• Provider information
• Capabilities (streaming, push notifications)
• Authentication requirements
• Supported input/output modes
• Skills (capabilities the agent can perform)

Agent cards are generated from:

1. YAML configuration in the agent_card section
2. Dynamically detected capabilities (streaming support, etc.)
3. Reasonable defaults for missing fields

Handler Details

• google_adk_handler wraps raw Google ADK Agent instances via ADKAgentAdapter so .invoke()/.stream() always exist.
• prepare_handler_params treats the name parameter as a literal, allowing YAML overrides without import errors.

Custom Handler Development

Subclass TaskHandler, implement process_task, and register via:

• Automatic discovery (--handler-package)
• Entry points in setup.py under a2a.task_handlers

Installation

Clone the repo and install the core library:

git clone https://github.com/yourusername/a2a.git
cd a2a
pip install -e .

Install optional extras as needed:

pip install -e ".[jsonrpc]"    # core JSON-RPC only
pip install -e ".[server]"     # HTTP, WS, SSE server
pip install -e ".[client]"     # CLI client
pip install -e ".[adk]"        # Google ADK agent support
pip install -e ".[full]"       # All features

After installation, run the server or client using uv run:

uv run a2a-server --host 0.0.0.0 --port 8000 --log-level info
uv run a2a-client --help

Requirements

• Python 3.9+
• HTTPX, WebSockets (for client)
• FastAPI, Uvicorn (for server)
• Pydantic v2+ (for JSON-RPC)

Testing

pytest