Metadata-Version: 2.4
Name: a2a-handler
Version: 0.3.0
Summary: An A2A Protocol client TUI and CLI.
Keywords: a2a,a2a-protocol,agent,agent-to-agent,ai,cli,tui
Author: Al Duncanson
Author-email: Al Duncanson <alDuncanson@proton.me>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: a2a-sdk[http-server]>=1.0.0,<2.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: starlette>=0.37.0
Requires-Dist: textual>=0.47.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: textual-serve>=1.1.0
Requires-Dist: mcp[cli]>=1.27.1,<2
Requires-Dist: truststore>=0.9.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: a2a-sdk[grpc]>=1.0.0,<2.0.0 ; extra == 'grpc'
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/alDuncanson/handler
Project-URL: Repository, https://github.com/alDuncanson/handler
Project-URL: Documentation, https://github.com/alDuncanson/handler/tree/main/docs
Project-URL: Issues, https://github.com/alDuncanson/handler/issues
Project-URL: Changelog, https://github.com/alDuncanson/handler/releases
Provides-Extra: grpc
Description-Content-Type: text/markdown

# Handler

[![CI](https://github.com/alDuncanson/handler/actions/workflows/ci.yml/badge.svg)](https://github.com/alDuncanson/handler/actions/workflows/ci.yml)
[![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v1.0.0-blue)](https://a2a-protocol.org/latest/)
[![PyPI version](https://img.shields.io/pypi/v/a2a-handler)](https://pypi.org/project/a2a-handler/)
[![PyPI - Status](https://img.shields.io/pypi/status/a2a-handler)](https://pypi.org/project/a2a-handler/)
[![Pepy total downloads](https://img.shields.io/pepy/dt/a2a-handler?label=total%20downloads)](https://pepy.tech/projects/a2a-handler)
[![GitHub stars](https://img.shields.io/github/stars/alDuncanson/handler)](https://github.com/alDuncanson/handler/stargazers)

Handler is an open-source [A2A protocol](https://github.com/a2aproject/A2A)
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](https://raw.githubusercontent.com/alDuncanson/Handler/73915875903b60dad6e4e404aa7ed91b6d94559f/assets/tui.png)

## 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](https://pypi.org/project/a2a-handler/) as a `uv` tool:

```bash
uv tool install a2a-handler
```

Or with [pipx](https://pipx.pypa.io/):

```bash
pipx install a2a-handler
```

Or with pip:

```bash
pip install a2a-handler
```

## Quick Start

Open the interactive terminal UI:

```bash
handler tui
```

Inspect an A2A server's agent card:

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

Send a message from the CLI:

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

Stream the reply, with a file attached:

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

List the agent's tasks:

```bash
handler task list --url URL
```

Open the full documentation:

```bash
handler docs
```

## Run Without Installing

Run Handler with `uvx`:

```bash
uvx --from a2a-handler handler
```

Run Handler with `pipx`:

```bash
pipx run a2a-handler
```

## 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:

```bash
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](https://handler.alduncanson.com/guides/agent-skill).
