Content
---
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:
```bash
# 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
```bash
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:
```bash
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
```bash
# 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:
```bash
echo "$GITHUB_TOKEN" | docker login ghcr.io -u <github-username> --password-stdin
```
Then pull and run:
```bash
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:
```bash
# 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
```mermaid
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
```mermaid
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.
