Handler

An A2A Protocol client TUI and CLI.

Install

Install with uv:

uv tool install a2a-handler

Or run Handler in an ephemeral environment:

uvx --from a2a-handler handler

Use

For a full list of commands and options:

handler --help

Server Agent

Handler includes a reference implementation of an A2A server agent built with Google ADK and LiteLLM, connecting to Ollama for local inference.

Use any model from Ollama's library:

handler server agent --model llama3.2:1b

Handler will prompt to pull missing models automatically.

Run with authentication:

handler server agent --auth

Copy the API key from the terminal output.

Webhook Server

Run Handler's webhook server to receive asynchronous push notifications from A2A server agents:

handler server push

Then send messages with push notifications enabled:

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

Sending Messages

Send a message and get a response:

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

Stream responses in real-time:

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

Continue a conversation using saved session state:

handler message send http://localhost:8000 "Follow up question" --continue

Authentication

Save credentials for an agent:

handler auth set http://localhost:8000 --api-key my-secret
handler auth set https://api.example.com --bearer eyJhbG...

TUI

Launch the terminal user interface:

handler tui

Agent Cards

Fetch an agent's card:

handler card get http://localhost:8000

And validate an agent card from a URL or a file:

handler card validate http://localhost:8000
handler card validate ./agent-card.json

Upgrade

Upgrade Handler to the latest version from PyPI:

uv tool upgrade a2a-handler

Contributing

See CONTRIBUTING.md.