Skip to main content
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

​
Verify installation

Confirm Handler is installed correctly: 
# Check version
handler version

# View help
handler --help
You should see the Handler CLI help output with all available commands: 
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: 
nix develop
This provides Python, uv, and just with all commands ready to use.

​
Troubleshooting

​
Command not found

If handler is not found after installation:
  1. 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
  2. Restart your shell: Close and reopen your terminal
  3. 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

Quickstart

Send your first message to an A2A agent

CLI reference

Explore all CLI commands in detail