README.md

metadata

title: A2A Validator
emoji: 🔬
colorFrom: green
colorTo: blue
sdk: docker
pinned: false

A2A Validator 🔬

A2A Validator is a focused web app for testing AI agents that speak the A2A (Agent-to-Agent) protocol. Paste an agent URL, connect, and the app will fetch the agent’s discovery document, validate it against the protocol, and provide a real-time message terminal. It’s a tool designed for the build/integration loop: tight feedback, zero ceremony.

The backend runs on FastAPI and Socket.IO, with a lightweight HTML/JS frontend. The core validator checks both the static Agent Card and the live events an agent emits. If the optional a2a-sdk is present, it's used for card resolution and streaming; if not, the app gracefully falls back to a "plain HTTP" mode for basic card linting.

---

✨ Features

• Inspector UI: A clean interface at /validator to enter an agent URL and optional custom HTTP headers for auth or tenancy.
• Smart Card Resolution: Forgivingly handles root URLs by following redirects and probing common well-known paths (e.g., /.well-known/agent.json).
• Inline Validation: Pretty-prints the agent's JSON card and displays any validation errors or warnings directly in the UI.
• Live Chat Terminal: When the a2a-sdk is installed, a real-time terminal connects via Socket.IO to stream messages to and from the agent.
• Real-time Message Linting: Live messages are marked with ✅ (compliant) or ⚠️ (non-compliant). Click any message to view the raw JSON.
• Integrated Debug Console: A resizable console shows raw server-side request/response logs, minimizing the need for browser DevTools.

---

🚀 Quick Start

Create a virtual environment, install dependencies, and run the server:

# 1. Create venv and activate
python3 -m venv .venv
source .venv/bin/activate

# 2. Install dependencies for editable mode
pip install -e .

# 3. Run the development server
make run

or

uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload

Point your browser to the Inspector UI:

➡️ http://localhost:7860/validator

You can also test the card fetch endpoint directly from your terminal:

curl -s -X POST localhost:7860/agent-card \
  -H 'content-type: application/json' \
  -d '{"url":"http://localhost:8080/","sid":"test"}' | jq

Installation (Docker) — pull from Docker Hub or GHCR

You can run A2A Validator as a single container. Choose your preferred registry, pull the image, and map a port.

Replace placeholders with your image path and tag:

• Docker Hub: docker.io/ruslanmv/a2a-validator
• GHCR: ghcr.io/ruslanmv/a2a-validator

Option 1 — Docker Hub

# Pull
docker pull docker.io/ruslanmv/a2a-validator

# Run (maps host 7860 → container 7860)
docker run --rm -p 7860:7860 docker.io/ruslanmv/a2a-validator

Option 2 — GitHub Container Registry (GHCR)

If needed, authenticate first:

echo "$GITHUB_TOKEN" | docker login ghcr.io -u <github-username> --password-stdin

Then pull and run:

docker pull ghcr.io/ruslanmv/a2a-validator

docker run --rm -p 7860:7860 ghcr.io/ruslanmv/a2a-validator

Quick smoke test

With the container running locally:

# Open the UI
# http://localhost:7860/validator

# Optional: test the card endpoint
curl -s -X POST http://localhost:7860/agent-card \
  -H 'content-type: application/json' \
  -d '{"url":"http://localhost:8080/","sid":"test"}' | jq

To stop it, press Ctrl+C (foreground) or docker stop <container-id> if you ran it detached.

---

🛠️ How It Works

The validator checks for common issues that break interoperability.

• Agent Card Validation: It checks for required fields (name, description, url, capabilities, skills, etc.), correct types, a semver-like version string, and a valid absolute URL.
• Message Validation: During a live session, it validates incoming events based on their kind. For example, task events must have an id and status.state, while message events must have a parts array and the correct role.

Architecture

flowchart LR
    subgraph Browser
        UI[Inspector UI]
    end

    subgraph Server [FastAPI App]
        API[/POST /agent-card<br/>GET /validator/]
        WS[[Socket.IO]]
    end

    subgraph Agent [A2A Agent]
        RPC[(JSON-RPC Endpoint)]
    end

    UI -- HTTP & WebSocket --> Server
    Server -- HTTP & JSON-RPC --> Agent

Sequence Diagram

sequenceDiagram
    participant U as UI
    participant S as Server
    participant A as Agent

    U->>S: POST /agent-card { url, sid }
    S->>A: Resolve + GET card (follows redirects)
    A-->>S: Card JSON
    S->>S: Validate Card
    S-->>U: { card, validation_errors }

    U->>S: socket 'initialize_client'
    S-->>U: 'client_initialized'
    U->>S: socket 'send_message' { message }
    S->>A: JSON-RPC call / stream
    A-->>S: Agent responses
    S->>S: Validate each response
    S-->>U: 'agent_response' with validation notes

Example card

---

⚙️ Configuration & Endpoints

The application is designed to work out of the box with minimal setup.

• GET /validator: Serves the Inspector UI.
• POST /agent-card: The API endpoint for fetching and validating an Agent Card.
• /socket.io: The path for real-time WebSocket connections.
• /healthz & /readyz: Standard health check endpoints.

Static assets are served from app/static and templates from app/templates. The main UI is validator.html, which extends a base template. The server creates an alias for /agent-card at the root, so the frontend script works correctly even when the validator is embedded in a larger application.

---

🔍 Troubleshooting

• 307 Temporary Redirect: If you paste a root URL (e.g., http://my-agent/) and see this, it often means the agent is redirecting to a docs page. The validator will automatically try to find the card at common paths like /.well-known/agent.json. If it still fails, try pasting the direct URL to the agent card JSON file.
• 404 Not Found on /agent-card: Ensure the API route alias is correctly configured in your app/main.py file. This is crucial if the validator_service router is mounted behind a prefix.
• "A2A SDK not installed": This is not an error but a feature. The app is running in its lightweight, HTTP-only mode. To enable chat and streaming tests, install the a2a-sdk package (pip install "a2a-sdk[http-server]").

---

📜 License

This project is licensed under the Apache-2.0 License. Use it, tweak it, ship it.