Handler is published to PyPI as a2a-handler and can be installed using multiple package managers. Choose the installation method that best fits your workflow.
Prerequisites
- Python 3.11 or higher - Handler requires Python 3.11+
- A package manager: uv, pipx, or pip
Handler is designed to be installed as a standalone tool using uv tool or pipx. This isolates Handler’s dependencies from your other Python projects.
Installation methods
uv (recommended)
pipx
pip
uv is an extremely fast Python package installer and resolver written in Rust.Install uv
If you don’t have uv installed:# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Install Handler
uv tool install a2a-handler
handler command will be available in your PATH.Run without installing
You can also run Handler from an ephemeral environment without installing:uvx --from a2a-handler handler
pipx installs Python CLI applications in isolated environments.Install pipx
If you don’t have pipx installed:# macOS
brew install pipx
pipx ensurepath
# Linux
python3 -m pip install --user pipx
python3 -m pipx ensurepath
# Windows
python -m pip install --user pipx
python -m pipx ensurepath
Install Handler
Run without installing
Standard pip installation (not recommended for CLI tools, as it doesn’t isolate dependencies).Install Handler
Using pip directly may conflict with your system Python packages. Consider using uv tool or pipx instead for better dependency isolation.
Verify installation
Confirm Handler is installed correctly:
# Check version
handler version
# View help
handler --help
Usage: handler [OPTIONS] COMMAND [ARGS]...
Handler - A2A protocol client CLI.
Options:
-v, --verbose Enable verbose logging
-d, --debug Enable debug logging
--help Show this message and exit.
Commands:
auth Manage authentication credentials for agents
card Agent card operations (get, validate)
mcp Run a local MCP server exposing A2A capabilities
message Send messages to A2A agents
server Run local servers (agent, push webhook)
session Manage saved sessions
task Task operations (get, cancel, notifications)
tui Launch the interactive terminal interface
version Display the current version
web Serve the TUI as a web application
Update Handler
Keep Handler up to date with the latest features and bug fixes:
uv tool upgrade a2a-handler
Development installation
For contributing to Handler or running from source:
# Clone the repository
git clone https://github.com/alDuncanson/handler.git
cd handler
# Install with uv (includes dev dependencies)
uv sync
# Run from source
uv run handler --help
Nix development environment
A hermetically sealed development environment is available with Nix:
This provides Python, uv, and just with all commands ready to use.
Troubleshooting
Command not found
If handler is not found after installation:
-
Check your PATH: Ensure the installation directory is in your PATH
- uv:
~/.local/bin (Unix) or %USERPROFILE%\.local\bin (Windows)
- pipx: Run
pipx ensurepath to add to PATH
-
Restart your shell: Close and reopen your terminal
-
Verify installation:
# For uv
uv tool list
# For pipx
pipx list
SSL certificate errors
Handler uses truststore to inject system certificates. If you encounter SSL errors:
# macOS - update certificates
/Applications/Python\ 3.11/Install\ Certificates.command
# Linux - install ca-certificates
sudo apt-get install ca-certificates # Debian/Ubuntu
sudo yum install ca-certificates # RHEL/CentOS
Permission errors
On Unix systems, you may need to make the binary executable:
chmod +x ~/.local/bin/handler
Next steps