A2A Debug Toolkit

A comprehensive toolkit for debugging and testing the A2A (Agent-to-Agent) communication protocol. This project consists of two components: a Quarkus-based A2A server implementation and a React-based debug client for interacting with A2A agents.

Components

1. a2a-debug-server

A Quarkus-based A2A server that implements the Agent-to-Agent protocol. This component acts as a test server that can be used to validate A2A client implementations.

Key Features:

• Full A2A protocol implementation using Quarkus
• REST endpoints for agent communication
• Dev UI for monitoring and testing
• Influence the result by passing special strings as message

2. a2a-debug-client

A pure frontend application built with React and TypeScript for debugging A2A agent interactions. It connects directly to A2A agents via the browser.

Key Features:

• Direct browser-to-agent communication using @a2a-js/sdk
• Start new conversations or resume existing tasks
• Real-time chat interface with JSON response inspection
• URL-based state management for easy sharing
• Task and context ID tracking with copy functionality

Quick Start

Running the Server

cd a2a-debug-server
./mvnw quarkus:dev

The server will be available at http://localhost:11001

Running the Client

cd a2a-debug-client
npm install
npm run dev

The client will be available at http://localhost:3000

Usage

1. Start the a2a-debug-server (or use any A2A-compliant agent)
2. Start the a2a-debug-client frontend
3. Enter the agent card URL (e.g., http://localhost:11001/.well-known/agent-card.json)
4. Start chatting with the agent or load an existing task

Server behavior

By default, the server will start an async task and respond with a "Still working..." status message on subsequent messages. You can influence the server's response by including special strings in your messages:

• COMPLETE_TASK in the initial message. Completes the task immediately (sync).
• COMPLETE_MESSAGE in the initial message. Returns a message instead of a task.
• COMPLETE in a follow-up message for an already running task. Completes the task.

Technology Stack

• Server: Quarkus, Java, A2A protocol implementation
• Client: React 18, TypeScript, Material UI, @a2a-js/sdk
• Build Tools: Maven (server), Vite (client)

Development

Each component has its own README with detailed development instructions:

• a2a-debug-server/README.md
• a2a-debug-client/README.md