GitHub - alDuncanson/Handler: A2A protocol client for your terminal

GitHub

2 min read Original article ↗

CI Coverage SLSA 2 A2A Protocol PyPI version PyPI - Status Pepy total downloads GitHub stars

Handler is an open-source A2A protocol client for software engineers building, testing, and operating agentic systems. It provides an interactive TUI, a scriptable CLI with structured output, and an MCP server that lets other agents integrate with A2A services directly. Handler also supports global and repo-scoped A2A server configuration with bearer, API key, HTTP Basic, mTLS, OAuth2 client credentials, and OpenID Connect auth.

Handler TUI connected to an A2A agent, showing the agent card and a completed assistant response

Features

  • Streams replies as they arrive, in the TUI and the CLI, and can stop a running task or answer an agent that pauses for input
  • Sends text, files (inline or by URL), and structured data, and shows the file and data parts agents send back
  • Lists, inspects, cancels, and resubscribes to tasks, and manages push notification configs with a bundled local webhook receiver
  • Speaks JSON-RPC and HTTP+JSON out of the box, gRPC with the grpc extra, and lets the agent card pick the transport
  • Requests A2A extensions and fetches the extended card an agent offers to authenticated clients
  • Keeps credentials on the origin you configured, never on a host an agent card happens to name

Install

Install Handler from the PyPI package as a uv tool:

uv tool install a2a-handler

Or with pipx:

Or with pip:

Quick Start

Open the interactive terminal UI:

Inspect an A2A server's agent card:

handler card get --url http://localhost:8000

Send a message from the CLI:

handler message send --url URL --text "hello"

Stream the reply, with a file attached:

handler message stream --url URL --text "Review this" --file ./report.pdf

List the agent's tasks:

handler task list --url URL

Open the full documentation:

Run Without Installing

Run Handler with uvx:

uvx --from a2a-handler handler

Run Handler with pipx:

Documentation

Read the documentation at https://handler.alduncanson.com.

For coding agents

The docs ship as an agent skill, regenerated on every deploy. Install it into Claude Code, Cursor, Windsurf, or any agent that reads the SKILL.md format:

npx skills add https://handler.alduncanson.com

Or fetch it by hand from https://handler.alduncanson.com/skill.md. For live lookups, agents can also use the hosted documentation MCP server at https://handler.alduncanson.com/mcp or the page index at https://handler.alduncanson.com/llms.txt. See the agent skill guide.