Quickstart

Get started with Handler by sending your first message to an A2A agent

This guide will walk you through your first interaction with an A2A agent using Handler. You’ll learn the basic commands for sending messages, managing sessions, and exploring agent capabilities.

Prerequisites

Before starting, ensure you have:

1. Installed Handler - See the installation guide
2. Python 3.11+ installed on your system
3. An A2A agent URL to connect to (or use the local server setup below)

If you don’t have an A2A agent to test with, you can run Handler’s built-in local agent (see Running a local agent below).

Your first message

Let’s send a simple message to an A2A agent:

1. Send a message

   Use the message send command to send text to an agent:

   handler message send https://agent.example.com "Hello, what can you do?"
   

   Handler will connect to the agent, send your message, and display the response:

   Sending to https://agent.example.com...
   
   Context ID: 550e8400-e29b-41d4-a716-446655440000
   Task ID: 660e8400-e29b-41d4-a716-446655440001
   State: completed
   
   Hello! I'm an A2A agent. I can help you with various tasks...
   

   The context_id and task_id are automatically saved to your session for conversation continuity.

2. Continue the conversation

   Send a follow-up message using the saved session:

   handler message send https://agent.example.com "Tell me more" --continue
   

   The --continue flag (or -C) uses the saved context and task IDs from your previous interaction.

3. Stream responses in real-time

   For long-running tasks or streaming responses, use the stream command:

   handler message stream https://agent.example.com "Write a short poem"
   

   You’ll see the response appear word-by-word as the agent generates it:

   Sending to https://agent.example.com...
   In circuits deep and pathways bright,
   Where data flows through endless night,
   An agent works with tireless grace,
   Connecting worlds in cyberspace.
   
   Context ID: 770e8400-e29b-41d4-a716-446655440002
   Task ID: 880e8400-e29b-41d4-a716-446655440003
   State: completed
   

Exploring agent capabilities

Before interacting with an agent, you can inspect its capabilities:

Get the agent card

handler card get https://agent.example.com

This displays the agent’s metadata, including:

• Name and description
• Supported skills
• Capabilities (streaming, push notifications)
• Content types (text, markdown, images)
• Authentication requirements

Validate the agent card

Ensure an agent card is valid according to A2A protocol:

handler card validate https://agent.example.com

Output:

Agent Card Validation

Valid: Yes
Agent: Example Agent
Protocol Version: 0.3.0
Source: https://agent.example.com

Capabilities:
  - Streaming: Yes
  - Push Notifications: Yes

Skills:
  - weather: Get current weather information
  - calculator: Perform mathematical calculations

Using the terminal UI (TUI)

For a more interactive experience, launch Handler’s terminal user interface:

handler tui

The TUI provides:

• Visual agent card display with syntax highlighting
• Real-time message streaming with markdown rendering
• Task and artifact management in dedicated tabs
• Session persistence across restarts
• Debug logs for troubleshooting

Navigate the TUI:

• Ctrl+Q - Quit
• / - Command palette
• Ctrl+M - Maximize focused panel
• Tab - Switch focus between panels

You can also serve the TUI as a web application:

handler web --port 8001

Then open http://localhost:8001 in your browser.

Working with sessions

Handler automatically manages sessions for conversation continuity:

List all sessions

handler session list

Output:

Saved Sessions

https://agent.example.com
  Context ID: 550e8400-e29b-41d4-a716-446655440000
  Task ID: 660e8400-e29b-41d4-a716-446655440001
  Credentials: Yes

https://another-agent.com
  Context ID: 990e8400-e29b-41d4-a716-446655440004
  Credentials: No

View a specific session

handler session show https://agent.example.com

Clear session data

# Clear specific agent
handler session clear https://agent.example.com

# Clear all sessions
handler session clear --all

Authentication

Many A2A agents require authentication. Handler supports bearer tokens and API keys:

Set credentials

Bearer token

handler auth set https://agent.example.com --bearer "your-token-here"

Credentials are securely stored in ~/.handler/sessions.json and automatically used for future requests.

Inline authentication

You can also provide credentials per-request:

handler message send https://agent.example.com "Hello" --bearer "token"

Clear credentials

handler auth clear https://agent.example.com

Running a local agent

Handler includes a reference A2A agent implementation for testing:

handler server agent --port 8000

This starts a local agent at http://localhost:8000 that you can interact with:

# In another terminal
handler message send http://localhost:8000 "Hello, local agent!"

The local agent uses LiteLLM for provider abstraction and supports:

• OpenAI, Anthropic, Google, and other LLM providers
• Ollama for local models
• Custom system prompts
• Streaming responses

Configure the local agent

Set environment variables to customize the agent:

export LITELLM_MODEL=gpt-4o-mini
export OPENAI_API_KEY=your-key-here
export AGENT_NAME="My Custom Agent"
export AGENT_DESCRIPTION="A helpful assistant"

handler server agent --port 8000

For Ollama:

export LITELLM_MODEL=ollama/llama3.2
handler server agent --port 8000

Task management

For long-running tasks, you can check status and cancel if needed:

Get task status

handler task get https://agent.example.com --task-id "task-123"

Cancel a task

handler task cancel https://agent.example.com --task-id "task-123"

Set up push notifications

Get notified when a task completes:

# Start a webhook receiver (in one terminal)
handler server push --port 9000

# Set notification for a task (in another terminal)
handler task notification set https://agent.example.com \
  --task-id "task-123" \
  --push-url "http://localhost:9000/webhook"

Next steps

Now that you’ve sent your first messages, explore more advanced features:

CLI reference

Complete reference for all CLI commands and options

TUI guide

Master the terminal user interface

MCP integration

Connect Handler to Claude Desktop and other AI assistants

Local server

Configure and deploy your own A2A agent

Common patterns

Quick checks

# Check if an agent is online
handler card get https://agent.example.com

# Validate before sending messages
handler card validate https://agent.example.com

# View current version
handler version

Debugging

# Enable verbose logging
handler --verbose message send https://agent.example.com "test"

# Enable debug logging
handler --debug message send https://agent.example.com "test"

Scripting

#!/bin/bash
# Send multiple messages in sequence

AGENT_URL="https://agent.example.com"

handler message send $AGENT_URL "Initialize task" --continue
handler message send $AGENT_URL "Process data" --continue  
handler message send $AGENT_URL "Generate report" --continue

Remember to handle authentication in automated scripts. Store tokens in environment variables or use Handler’s credential storage:

export AGENT_TOKEN="your-token"
handler auth set $AGENT_URL --bearer "$AGENT_TOKEN"