A2A Command Line Interface

The A2A CLI provides a convenient way to interact with A2A-compatible agents from the command line. It's useful for testing, debugging, and automating interactions with agents.

Installation

You can install the A2A CLI using pip:

pip install a2a-cli

Or clone the repository and install from source:

git clone https://github.com/google/A2A.git
cd A2A/tools/cli
pip install -e .

Basic Usage

Discovering Agents

You can discover an agent's capabilities by fetching its Agent Card:

a2a discover https://example-agent.com/a2a

This will display the agent's name, description, skills, and supported modes of interaction.

Creating Tasks

To create a new task with an agent:

a2a create --url https://example-agent.com/a2a --message "What's the weather in San Francisco today?"

If the agent requires authentication:

a2a create --url https://example-agent.com/a2a --auth-token "your-token" --message "What's the weather in San Francisco today?"

Getting Task Status

After creating a task, you can check its status:

a2a get --url https://example-agent.com/a2a --task-id "task_123456"

Interactive Mode

For multi-turn conversations, you can use interactive mode:

a2a interactive --url https://example-agent.com/a2a

This will start a session where you can chat with the agent in a REPL-like interface.

Advanced Features

Streaming Responses

To stream responses from agents that support SSE:

a2a create --url https://example-agent.com/a2a --message "Generate a detailed report on climate change" --stream

Multi-Part Messages

You can send multi-part messages, including files:

a2a create --url https://example-agent.com/a2a --text "Analyze this image" --file image.jpg

Saving Artifacts

To save artifacts from a task to a local file:

a2a get --url https://example-agent.com/a2a --task-id "task_123456" --save-artifacts ./artifacts/

Push Notifications

You can register for push notifications:

a2a notifications set --url https://example-agent.com/a2a --task-id "task_123456" --callback "https://your-server.com/webhook"

And then get the current notification settings:

a2a notifications get --url https://example-agent.com/a2a --task-id "task_123456"

Scripting and Automation

Environment Variables

The CLI supports environment variables for common parameters:

export A2A_URL=https://example-agent.com/a2a
export A2A_AUTH_TOKEN=your-token
 
# Now you can omit these parameters
a2a create --message "What's the weather in San Francisco today?"

JSON Output

For scripting, you can request JSON output:

a2a create --url https://example-agent.com/a2a --message "What's the time in Tokyo?" --json

Batch Processing

Process multiple messages in batch mode:

a2a batch --url https://example-agent.com/a2a --input messages.txt --output results.json

Where messages.txt contains one message per line.

Configuration

You can create a configuration file to store commonly used settings:

a2a config set default_url https://example-agent.com/a2a
a2a config set default_auth_token your-token

List current configuration:

a2a config list

Agent Comparison

Compare responses from multiple agents:

a2a compare --agents agent1=https://agent1.com/a2a,agent2=https://agent2.com/a2a --message "Explain quantum computing"

Task Management

List recent tasks:

a2a list --url https://example-agent.com/a2a

Cancel a running task:

a2a cancel --url https://example-agent.com/a2a --task-id "task_123456"

Development Tools

Validate Agent Card

Check if an Agent Card follows the A2A specification:

a2a validate-card agent-card.json

Mock Server

Start a mock A2A server for testing:

a2a mock-server --port 8000

Examples

Simple Weather Query

a2a create --url https://weather-agent.example.com/a2a --message "What's the weather in New York?"

Multi-turn Conversation

# Start a conversation
TASK_ID=$(a2a create --url https://travel-agent.example.com/a2a --message "I want to plan a trip to Japan" --json | jq -r '.taskId')
 
# Continue the conversation with follow-up questions
a2a send --url https://travel-agent.example.com/a2a --task-id "$TASK_ID" --message "What's the best time to visit Tokyo?"
a2a send --url https://travel-agent.example.com/a2a --task-id "$TASK_ID" --message "Can you suggest a 7-day itinerary?"

Working with Files

# Send an image for analysis
a2a create --url https://vision-agent.example.com/a2a --text "What's in this image?" --file picture.jpg
 
# Get results and save to a file
a2a get --url https://vision-agent.example.com/a2a --task-id "task_123456" --save-artifacts ./results/

Troubleshooting

Logging

Enable detailed logging for debugging:

a2a create --url https://example-agent.com/a2a --message "Hello" --verbose

For even more detail:

a2a create --url https://example-agent.com/a2a --message "Hello" --debug

Connection Issues

Test the connection to an A2A server:

a2a ping https://example-agent.com/a2a

Common Errors

Authentication Failures: Check that your auth token is valid
Invalid URL: Ensure the URL ends with /a2a or is the correct endpoint
Timeout Errors: Try increasing the timeout with --timeout 60
Format Errors: Verify the agent supports the content type you're sending

The A2A CLI provides a powerful interface for interacting with A2A-compatible agents from the command line. It supports both simple interactions and advanced features like streaming, multi-turn conversations, and working with multi-modal content.

CLI