https://github.com/alduncanson/handler

A2A Protocol client and developer toolkit.
https://github.com/alduncanson/handler

a2a a2a-cli a2a-client a2a-protocol a2a-server adk agent ai ai-agents cli litellm mcp mcp-server ollama pypi python tui uv

Last synced: about 2 months ago
JSON representation

A2A Protocol client and developer toolkit.

• Host: GitHub
• URL: https://github.com/alduncanson/handler
• Owner: alDuncanson
• License: gpl-3.0
• Created: 2025-11-16T23:10:16.000Z (7 months ago)
• Default Branch: main
• Last Pushed: 2026-04-08T04:05:56.000Z (2 months ago)
• Last Synced: 2026-04-08T06:00:56.545Z (2 months ago)
• Topics: a2a, a2a-cli, a2a-client, a2a-protocol, a2a-server, adk, agent, ai, ai-agents, cli, litellm, mcp, mcp-server, ollama, pypi, python, tui, uv
• Language: Python
• Homepage: https://handler.alduncanson.com
• Size: 1.59 MB
• Stars: 39
• Watchers: 1
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
# 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-v0.3.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/)

[![PyPI monthly downloads](https://img.shields.io/pypi/dm/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 TUI](https://github.com/alDuncanson/Handler/blob/main/assets/handler-tui.png?raw=true)

Handler is an open-source [A2A protocol](https://github.com/a2aproject/A2A) client for your terminal.

Use the TUI or CLI to send messages, manage tasks, and inspect agent cards.

An included MCP server lets your AI assistant talk to A2A agents too.

## Install

```bash

uv tool install a2a-handler

```

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

```bash

pipx install a2a-handler   # or: pip install a2a-handler

```

## Quick Start

```bash

handler tui                              # launch the interactive TUI

handler message send URL "hello"         # send a message from the CLI

handler card get URL                     # fetch an agent card

handler mcp                              # start the MCP server

handler server run agent                 # run the bundled reference agent

```

## Run Without Installing

```bash

uvx --from a2a-handler handler           # or: pipx run a2a-handler

```

## Servers

Handler supports named servers in `$XDG_CONFIG_HOME/handler/servers.toml`

(global) and `.handler/servers.toml` (repo-local).

```toml

version = 1

[servers.local]

url = "http://localhost:8000"

[servers.local.auth]

type = "bearer"

env = "HANDLER_LOCAL_TOKEN"

```

See [docs/](docs) for the full auth reference covering bearer, API key, mTLS,

and OAuth2.

## Development

A [hermetic](https://zero-to-nix.com/concepts/hermeticity/) dev environment

is available via [Nix](https://zero-to-nix.com/concepts/nix/):

```bash

nix develop

```

The Mintlify docs source lives in `docs/`.

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.