DOCSEARCHbyAlgolia
Submit Docs

A2A Inspector

repository·main·Indexed 19 days ago

https://github.com/a2aproject/a2a-inspector

A web-based debugging tool for the Agent2Agent (A2A) protocol. It enables developers to validate agent cards, interact with agents via a live chat interface, and inspect raw JSON-RPC 2.0 communication through a debug console.

Tokens
1.7K
Snippets
6
Records
8
Agent score
66%

What's inside a2a-inspector

  1. What is the A2A Protocol Inspector?

    main
    The A2A Inspector is a web-based tool for developers to inspect, debug, and validate servers implementing the A2A (Agent2Agent) protocol. It allows you to connect to an A2A agent via a base URL, view the agent's card, perform specification compliance checks, interact via a live chat interface, and debug raw JSON-RPC 2.0 messages through a slide-out debug console.

  2. Install and set up the A2A Inspector locally

    main

    To run the A2A Inspector locally for development, follow these steps to clone the repository, install Python dependencies using uv, and install Node.js dependencies for the frontend.

    1. Clone the repository

    git clone https://github.com/a2aproject/a2a-inspector.git
cd a2a-inspector

    2. Install Dependencies

    Backend (Python): From the root directory, use uv sync to install exact package versions into a virtual environment.

    uv sync

    Frontend (Node.js): Navigate to the frontend directory and use npm to install packages.

    cd frontend
npm install
cd ..
    git clone https://github.com/a2aproject/a2a-inspector.git
cd a2a-inspector
uv sync
cd frontend
npm install
cd ..

  3. Run the A2A Inspector locally for development

    main

    For active development with live-reloading for both frontend and backend, use one of the following two methods.

    Method 1: Using the convenience script (Recommended)

    This script starts both the frontend build process and the backend server simultaneously.

    chmod +x scripts/run.sh
bash scripts/run.sh

    Method 2: Manual execution in separate terminals

    If you prefer running processes manually, open two terminals from the project root:

    Terminal 1 (Frontend):

    cd frontend
npm run build -- --watch

    Terminal 2 (Backend):

    cd backend
uv run app.py

    Once running, access the inspector at http://127.0.0.1:5001.

    # Recommended way
chmod +x scripts/run.sh
bash scripts/run.sh

  4. Run the A2A Inspector using Docker

    main

    If you want to run the application without managing local Python or Node.js environments, use Docker. This builds the entire application (frontend and backend) into a single container.

    1. Build the image:
    docker build -t a2a-inspector .
    1. Run the container: Run the container in detached mode, mapping port 8080.
    docker run -d -p 8080:8080 a2a-inspector

    Once running, access the inspector at http://127.0.0.1:8080.

    docker build -t a2a-inspector .
docker run -d -p 8080:8080 a2a-inspector

  5. Debug logs and observability via Socket.IO

    main

    The inspector provides real-time debugging information via the debug_log Socket.IO event. This allows developers to see the raw request/response lifecycle between the inspector and the agent.

    Event: debug_log

    • Payload:
      • type: The category of the log (e.g., request, response, http-agent-card).
      • data: The actual payload being logged.
      • id: The ID associated with the event (e.g., the message ID or request ID).

  6. Fetch an Agent Card via POST /agent-card

    main

    The /agent-card endpoint allows you to fetch and validate an A2A Agent Card from a specific URL. This is useful for inspecting the capabilities and configuration of an agent before establishing a full connection.

    Request Body Requirements:

    • url: The URL of the agent card.
    • sid: A session ID (provided by the frontend/client) used for correlating debug logs.
    • custom_headers: (Optional) Any non-standard HTTP headers to include in the request to the agent.

    Response:

    • Returns a JSON object containing the card data and any validation_errors found during the process.
    • Returns 400 if required fields are missing.
    • Returns 502 if the agent is unreachable.
    • Returns 500 on internal server errors.
    {
  "url": "https://agent.example.com/card.json",
  "sid": "some-session-id"
}

  7. Send a message to an agent via Socket.IO

    main

    Once a client is initialized, use the send_message event to communicate with the agent. The backend handles message construction, including text parts and file attachments.

    Event: send_message

    • Payload:
      • message: The text content of the message.
      • id: (Optional) A unique ID for the message. If not provided, a UUID is generated.
      • contextId: (Optional) Used for multi-turn conversation tracking.
      • metadata: (Optional) Additional metadata for the message.
      • attachments: (Optional) A list of attachment objects.
        • data: The raw bytes of the file.
        • mimeType: The MIME type of the file.

    Response (agent_response event):

    • The backend streams responses from the agent. Each response is emitted as an agent_response event.
    • The response payload includes the id (correlated to the request ID) and the actual event data (e.g., Task, Message, TaskStatusUpdateEvent).
    • The backend also emits debug_log events for observability.
    // Example Socket.IO client-side call
socket.emit('send_message', {
  message: 'Hello, agent!',
  id: 'msg-123',
  attachments: [
    {
      data: [0x01, 0x02, 0x03], // ArrayBuffer or similar
      mimeType: 'application/octet-stream'
    }
  ]
});

socket.on('agent_response', (response) => {
  console.log('Received response:', response);
});

  8. Initialize an A2A Client via Socket.IO

    main

    To start a session with an agent, emit the initialize_client event over Socket.IO. This sets up the A2ACardResolver, creates a Client using the ClientFactory, and prepares the transport protocol.

    Event: initialize_client

    • Payload:
      • url: The Agent Card URL.
      • customHeaders: (Optional) A dictionary of custom headers to use for the client connection.

    Success Response (client_initialized event):

    • status: "success"
    • transport: The protocol being used (e.g., jsonrpc, http_json, grpc).
    • inputModes: List of supported input modes (e.g., ['text/plain']).
    • outputModes: List of supported output modes.

    Error Response (client_initialized event):

    • status: "error"
    • message: Description of the error.
    // Example Socket.IO client-side call
socket.emit('initialize_client', {
  url: 'https://agent.example.com/card.json',
  customHeaders: { 'Authorization': 'Bearer token' }
});

socket.on('client_initialized', (data) => {
  console.log(data.status, data.transport);
});