a2a-debugger

README

A2A Debugger

The ultimate A2A (Agent-to-Agent) troubleshooting and debugging tool

A powerful command-line utility for debugging, monitoring, and inspecting A2A servers. Connect to A2A servers, list tasks, view conversation histories, and inspect task statuses with ease.

⚠️ Warning

This project is in its early stages of development.

Breaking changes are expected as we actively develop and refine the tool. Use with caution in production environments and be prepared for API changes, configuration format updates, and command-line interface modifications between versions.

We recommend pinning to specific versions in your scripts and monitoring the CHANGELOG.md for breaking changes.

🚀 Features

• Server Connectivity: Test connections to A2A servers and retrieve agent information
• Task Management: List, filter, and inspect tasks with detailed status information
• Real-time Streaming: Submit streaming tasks and monitor real-time agent responses
• Streaming Summaries: Summaries with Task IDs, durations, and event counts
• Conversation History: View detailed conversation histories and message flows
• Agent Information: Retrieve and display agent cards with capabilities
• Configuration Management: Set, get, and list configuration values with namespace commands
• Flexible Configuration: Support for configuration files and environment variables
• Debug Logging: Comprehensive logging with configurable verbosity levels
• Namespace Commands: Organized command structure with config and tasks namespaces

📦 Installation

Quick Install (Recommended)

Use our install script to automatically download and install the latest binary:

curl -fsSL https://raw.githubusercontent.com/inference-gateway/a2a-debugger/main/install.sh | bash

Or download and run the script manually:

wget https://raw.githubusercontent.com/inference-gateway/a2a-debugger/main/install.sh
chmod +x install.sh
./install.sh

Install Options:

• Install specific version: ./install.sh --version v1.0.0
• Custom install directory: INSTALL_DIR=~/bin ./install.sh
• Show help: ./install.sh --help

Using Go Install

go install github.com/inference-gateway/a2a-debugger@latest

From Release

Download the latest binary from the releases page.

Build from Source

git clone https://github.com/inference-gateway/a2a-debugger.git
cd a2a-debugger
task build

🔧 Usage

Quick Start

Test connection to an A2A server:

a2a connect --server-url http://localhost:8080

Set server URL in configuration:

a2a config set server-url http://localhost:8080

List all tasks:

a2a tasks list

Get specific task details:

a2a tasks get <task-id>

View conversation history:

a2a tasks history <context-id>

Command Structure

The A2A Debugger uses a namespace-based command structure for better organization:

Config Commands

a2a config set <key> <value>    # Set a configuration value
a2a config get <key>            # Get a configuration value
a2a config list                 # List all configuration values

Task Commands

a2a tasks list                     # List available tasks
a2a tasks get <task-id>            # Get detailed task information
a2a tasks history <context-id>     # Get conversation history for a context
a2a tasks submit <message>         # Submit a task and get response
a2a tasks submit-streaming <msg>   # Submit streaming task with real-time responses and summary

Server Commands

a2a connect                     # Test connection to A2A server
a2a agent-card                  # Get agent card information

Configuration

Create a configuration file at ~/.a2a.yaml:

server-url: http://localhost:8080
timeout: 30s
debug: false
insecure: false

Command Options

Global Options

• --server-url: A2A server URL (default: http://localhost:8080)
• --timeout: Request timeout (default: 30s)
• --debug: Enable debug logging
• --insecure: Skip TLS verification
• --config: Config file path

Task List Options

• --state: Filter by task state (submitted, working, completed, failed)
• --context-id: Filter by context ID
• --limit: Maximum number of tasks to return (default: 50)
• --offset: Number of tasks to skip (default: 0)

Task Get Options

• --history-length: Number of history messages to include

Examples

Configuration Management

# Set server URL in config
$ a2a config set server-url http://localhost:8080

✅ Configuration updated: server-url = http://localhost:8080

# Get current server URL
$ a2a config get server-url

server-url = http://localhost:8080

# List all configuration
$ a2a config list

📋 Configuration:

  server-url = http://localhost:8080
  timeout = 30s
  debug = false

Connect and view agent information

$ a2a connect --server-url http://localhost:8080

✅ Successfully connected to A2A server!

Agent Information:
  Name: My A2A Agent
  Description: A helpful assistant agent
  Version: 1.0.0
  URL: http://localhost:8080

Capabilities:
  Streaming: true
  Push Notifications: false
  State Transition History: true

List tasks with filtering

$ a2a tasks list --state working --limit 5

📋 Tasks (Total: 23, Showing: 5)

1. Task ID: task-abc123
   Context ID: ctx-xyz789
   Status: working
   Message ID: msg-456
   Role: assistant

2. Task ID: task-def456
   Context ID: ctx-uvw123
   Status: working
   Message ID: msg-789
   Role: user

View detailed task information

$ a2a tasks get task-abc123

� Task Details

ID: task-abc123
Context ID: ctx-xyz789
Status: completed

Current Message:
  Message ID: msg-456
  Role: assistant
  Parts: 1
    1. Kind: text
       Text: Hello! How can I help you today?

View conversation history

$ a2a tasks history ctx-xyz789

💬 Conversation History for Context: ctx-xyz789

Task: task-abc123 (Status: completed)
  1. [user] msg-123
     1: I need help with my project
  2. [assistant] msg-456
     1: Hello! How can I help you today?

🛠️ Development

Prerequisites

• Go 1.24 or later
• Task for build automation

Available Tasks

task generate    # Generate code from schemas
task lint       # Run linting
task build      # Build the application
task test       # Run tests
task clean      # Clean build artifacts

Development Workflow

1. Make your changes
2. Run task generate to update generated files
3. Run task lint to check code quality
4. Run task build to verify compilation
5. Run task test to ensure all tests pass

📚 Related Projects

• Inference Gateway - Main project
• A2A ADK - Agent Development Kit
• Go SDK - Go SDK for Inference Gateway
• TypeScript SDK - TypeScript SDK
• Python SDK - Python SDK
• Documentation - Project documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.