Metadata-Version: 2.4
Name: a2a-handler
Version: 0.1.11
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: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
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>=0.3.22
Requires-Dist: click>=8.0.0
Requires-Dist: rich-click>=1.8.0
Requires-Dist: google-adk>=0.5.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: litellm>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.47.0
Requires-Dist: uvicorn>=0.30.0
Requires-Python: >=3.11
Project-URL: Changelog, https://github.com/alDuncanson/handler/releases
Project-URL: Documentation, https://github.com/alDuncanson/handler#readme
Project-URL: Homepage, https://github.com/alDuncanson/handler
Project-URL: Issues, https://github.com/alDuncanson/handler/issues
Project-URL: Repository, https://github.com/alDuncanson/handler
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-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 downloads](https://img.shields.io/pypi/dm/a2a-handler)](https://pypi.org/project/a2a-handler/)
[![GitHub stars](https://img.shields.io/github/stars/alDuncanson/handler)](https://github.com/alDuncanson/handler/stargazers)

An [A2A](https://github.com/a2aproject/A2A) Protocol client TUI and CLI.

![Handler TUI](https://github.com/alDuncanson/Handler/blob/main/assets/handler-tui.png?raw=true)

## Install

Install with [uv](https://github.com/astral-sh/uv):

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

Or run Handler in an ephemeral environment:

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

## Use

For a full list of commands and options:

```bash
handler --help
```

### Server Agent

Handler includes a reference implementation of an A2A server agent built with [Google ADK](https://github.com/google/adk-python) and [LiteLLM](https://github.com/BerriAI/litellm), connecting to [Ollama](https://github.com/ollama/ollama) for local inference.

Use any model from [Ollama's library](https://ollama.com/library):

```bash
handler server agent --model llama3.2:1b
```
> Handler will prompt to pull missing models automatically.

Run with authentication:

```bash
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:

```bash
handler server push
```

Then send messages with push notifications enabled:

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

### Sending Messages

Send a message and get a response:

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

Stream responses in real-time:

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

Continue a conversation using saved session state:

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

### Authentication

Save credentials for an agent:

```bash
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:

```bash
handler tui
```

### Agent Cards

Fetch an agent's card:

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

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

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

## Upgrade

Upgrade Handler to the latest version from [PyPI](https://pypi.org/project/a2a-handler/):

```bash
uv tool upgrade a2a-handler
```

## Contributing

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