Handler Documentation

Installation

Install Handler using uv:

uv tool install a2a-handler

Or run in an ephemeral environment:

uvx --from a2a-handler handler

For a full list of commands and options:

handler --help

Shell Completion

Handler supports tab completion in bash, zsh, and fish shells. Add one of the following to your shell configuration file:

Bash

Add to ~/.bashrc:

eval "$(_HANDLER_COMPLETE=bash_source handler)"

source ~/.bashrc

Zsh

Add to ~/.zshrc:

eval "$(_HANDLER_COMPLETE=zsh_source handler)"

source ~/.zshrc

Fish

Add to ~/.config/fish/config.fish:

_HANDLER_COMPLETE=fish_source handler | source

source ~/.config/fish/config.fish

Global Options

These options are available for all commands:

--verbose, -v: Enable verbose logging.
--debug, -d: Enable debug logging.

Messages

Send messages to A2A agents and receive responses.

handler message send

Send a message to an agent and receive a response.

handler message send <agent_url> <text> [options]

Arguments

agent_url: The URL of the A2A agent to send the message to.
text: The message text to send.

Options

--stream, -s: Stream responses in real-time.
--context-id: Context ID for conversation continuity.
--task-id: Task ID to continue.
--continue, -C: Continue from saved session state.
--push-url: Webhook URL for push notifications.
--push-token: Authentication token for push notifications.
--bearer, -b: Bearer token for authentication (overrides saved credentials).
--api-key, -k: API key for authentication (overrides saved credentials).

Examples

# Basic message
handler message send http://localhost:8000 "What can you help me with?"

# Continue a conversation
handler message send http://localhost:8000 "Follow up question" --continue

# With push notifications
handler message send http://localhost:8000 "hello" --push-url http://localhost:9000/webhook

handler message stream

Send a message and stream the response in real-time. This is equivalent to handler message send --stream.

handler message stream <agent_url> <text> [options]

Example

handler message stream http://localhost:8000 "Tell me a story"

Tasks

Manage A2A tasks including retrieval, cancellation, and push notifications.

handler task get

Retrieve the current status of a task.

handler task get <agent_url> <task_id> [options]

Arguments

agent_url: The URL of the A2A agent.
task_id: The ID of the task to retrieve.

Options

--history-length, -n: Number of history messages to include.
--bearer, -b: Bearer token (overrides saved credentials).
--api-key, -k: API key (overrides saved credentials).

handler task cancel

Request cancellation of a task.

handler task cancel <agent_url> <task_id> [options]

Options

--bearer, -b: Bearer token (overrides saved credentials).
--api-key, -k: API key (overrides saved credentials).

handler task resubscribe

Resubscribe to a task's SSE stream after disconnection.

handler task resubscribe <agent_url> <task_id> [options]

Options

--bearer, -b: Bearer token (overrides saved credentials).
--api-key, -k: API key (overrides saved credentials).

handler task notification set

Configure a push notification webhook for a task.

handler task notification set <agent_url> <task_id> --url <webhook_url> [options]

Options

--url, -u (required): Webhook URL to receive notifications.
--token, -t: Authentication token for the webhook.
--bearer, -b: Bearer token (overrides saved credentials).
--api-key, -k: API key (overrides saved credentials).

handler task notification get

Get the push notification configuration for a task.

handler task notification get <agent_url> <task_id> [options]

Options

--config-id, -c: Specific push notification config ID.
--bearer, -b: Bearer token (overrides saved credentials).
--api-key, -k: API key (overrides saved credentials).

Agent Cards

Retrieve and validate A2A agent cards.

handler card get

Retrieve an agent's card and display it as JSON.

handler card get <agent_url> [options]

Arguments

agent_url: The URL of the A2A agent.

Options

--authenticated, -a: Request authenticated extended card.

Example

handler card get http://localhost:8000

handler card validate

Validate an agent card from a URL or local file.

handler card validate <source>

Arguments

source: URL of an agent or path to a local agent card JSON file.

Examples

# Validate from URL
handler card validate http://localhost:8000

# Validate from file
handler card validate ./agent-card.json

Servers

Run local A2A servers for development and testing.

handler server agent

Start a local A2A agent server. This is a reference implementation built with Google ADK and LiteLLM, connecting to Ollama for local inference.

handler server agent [options]

Options

--host: Host to bind to. Default: 0.0.0.0
--port: Port to bind to. Default: 8000
--auth / --no-auth: Require API key authentication. Default: --no-auth
--api-key: Specific API key to use. If not set, one is auto-generated when --auth is enabled.
--model, -m: Model to use (e.g., llama3.2:1b, qwen3, gemini-2.0-flash). Use any model from Ollama's library.

Examples

# Basic server
handler server agent

# With a specific model
handler server agent --model llama3.2:1b

# With authentication
handler server agent --auth

Note: Handler will prompt to pull missing models automatically.

handler server push

Start a local webhook server for receiving push notifications from A2A agents.

handler server push [options]

Options

--host: Host to bind to. Default: 127.0.0.1
--port: Port to bind to. Default: 9000

Example

# Start webhook server
handler server push

# Send a message with push notifications
handler message send http://localhost:8000 "hello" --push-url http://localhost:9000/webhook

Sessions

Manage saved session state for maintaining conversation context across commands.

handler session list

List all saved sessions.

handler session list

handler session show

Display session state for a specific agent.

handler session show <agent_url>

Arguments

agent_url: The URL of the A2A agent.

handler session clear

Clear saved session state.

handler session clear [agent_url] [options]

Arguments

agent_url: The URL of the agent to clear. Optional if using --all.

Options

--all, -a: Clear all saved sessions.

Examples

# Clear session for one agent
handler session clear http://localhost:8000

# Clear all sessions
handler session clear --all

Authentication

Manage authentication credentials for A2A agents.

handler auth set

Set authentication credentials for an agent. Provide either --bearer or --api-key (not both).

handler auth set <agent_url> [options]

Arguments

agent_url: The URL of the A2A agent.

Options

--bearer, -b: Bearer token for authentication.
--api-key, -k: API key for authentication.
--api-key-header: Header name for API key. Default: X-API-Key

Examples

# Set API key
handler auth set http://localhost:8000 --api-key my-secret

# Set bearer token
handler auth set https://api.example.com --bearer eyJhbG...

handler auth show

Show authentication credentials for an agent (values are masked).

handler auth show <agent_url>

handler auth clear

Clear authentication credentials for an agent.

handler auth clear <agent_url>

MCP Server

Run a local Model Context Protocol (MCP) server exposing Handler's A2A functionality as MCP tools and resources.

handler mcp

Start an MCP server that can be connected to from any MCP-compatible client (Claude Desktop, Cursor, etc.).

handler mcp [options]

Options

--transport, -t: Transport protocol to use. Choices: stdio, sse, streamable-http. Default: stdio

Available Tools

The MCP server exposes the following tools:

Card Tools

validate_agent_card – Validate an agent card from URL or file
get_agent_card – Retrieve an agent's full card details

Message Tools

send_message – Send messages to agents with session/auth support

Task Tools

get_task – Get task status and details
cancel_task – Cancel a running task
set_task_notification – Configure push notification webhooks
get_task_notification – Get push notification config

Session Tools

list_sessions – List all saved sessions
get_session_info – Get session for a specific agent
clear_session_data – Clear saved session state

Auth Tools

set_agent_credentials – Save bearer token or API key
clear_agent_credentials – Remove saved credentials

Claude Desktop Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "handler": {
      "command": "handler",
      "args": ["mcp"]
    }
  }
}

Terminal User Interface

Handler includes an interactive terminal interface for working with A2A agents.

handler tui

Launch the interactive terminal interface.

handler tui

Features

Connect to multiple A2A agents
Send messages and view responses
Stream responses in real-time
Inspect tasks and view artifacts
Manage sessions and authentication
View agent cards and capabilities

Web Interface

Serve the TUI as a web application accessible in your browser.

handler web

Start a web server that serves the TUI interface.

handler web [options]

Options

--host: Host to bind to. Default: localhost
--port, -p: Port to bind to. Default: 8001

Example

handler web --port 3000

Version

handler version

Display the current Handler version.

handler version