A2A Registry

A community-driven, open-source directory of AI agents using the A2A Protocol

Overview

The A2A Registry is the discovery layer for AI agents. We index live, hosted agents that implement the A2A Protocol, making them discoverable by other agents and applications.

Key principle: We trust the agent card. If your agent publishes a valid .well-known/agent-card.json, you can register it with a single API call.

Register Your Agent

Make sure your agent publishes a valid agent card at https://your-agent.com/.well-known/agent-card.json, then:

curl -X POST https://a2aregistry.org/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{"wellKnownURI": "https://your-agent.com/.well-known/agent.json"}'

That's it. We fetch your agent card and register it automatically. The worker checks your agent's health every 30 minutes and updates conformance status.

Find Agents

Web UI: a2aregistry.org

API:

# List standard (A2A-conformant) agents
curl https://a2aregistry.org/api/agents?conformance=standard

# Search by keyword
curl https://a2aregistry.org/api/agents?search=translation

# Filter by skill tag
curl https://a2aregistry.org/api/agents?skill=weather

# Get stats
curl https://a2aregistry.org/api/stats

Python Client:

pip install a2a-registry-client

from a2a_registry import APIRegistry

registry = APIRegistry()
agents = registry.get_all()
results = registry.search("weather")

MCP Server (for AI assistants):

{
  "mcpServers": {
    "a2a-registry": {
      "url": "https://a2aregistry.org/mcp/"
    }
  }
}

Agent Card Format

Your .well-known/agent-card.json must follow the A2A Protocol AgentCard specification:

{
  "protocolVersion": "0.3.0",
  "name": "WeatherBot",
  "description": "Real-time weather information and forecasts",
  "url": "https://api.weatherbot.com/a2a",
  "version": "1.0.0",
  "provider": {
    "organization": "Weather Services Inc",
    "url": "https://weatherbot.com"
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["application/json"],
  "skills": [
    {
      "id": "current-weather",
      "name": "Current Weather",
      "description": "Get current weather conditions",
      "tags": ["weather", "forecast"],
      "inputModes": ["text/plain"],
      "outputModes": ["application/json"]
    }
  ]
}

API Reference

Base URL: https://a2aregistry.org/api

Endpoint	Method	Description
/agents/register	POST	Register agent by wellKnownURI
/agents	GET	List/search agents
/agents/{id}	GET	Get agent details
/agents/{id}	PUT	Re-fetch and update agent from wellKnownURI
/agents/{id}	DELETE	Remove agent (ownership verified)
/agents/{id}/health	GET	Get health status
/agents/{id}/uptime	GET	Get uptime metrics
/agents/{id}/chat	POST	Proxy a chat message to an agent
/stats	GET	Registry statistics

Query Parameters (GET /agents)

Parameter	Description
search	Full-text search across name, description, author
skill	Filter by skill tag
capability	Filter by A2A capability (streaming, pushNotifications)
author	Filter by author name
conformance	standard (A2A spec compliant) or non-standard
limit	Max results (default: 50, max: 100)
offset	Pagination offset

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    a2aregistry.org                          │
├─────────────────────────────────────────────────────────────┤
│  Frontend (React)  │  API (FastAPI)  │  Worker (Background) │
│   - Browse agents  │  - CRUD agents  │  - Health checks     │
│   - Search/filter  │  - Registration │  - Uptime tracking   │
│   - Agent details  │  - MCP server   │  - Conformance check │
└─────────────────────────────────────────────────────────────┘
                              │
                      ┌───────┴───────┐
                      │  PostgreSQL   │
                      │  (Cloud SQL)  │
                      └───────────────┘

Deployment: GKE Autopilot with Helm charts (see /helm/a2aregistry/)

Project Structure

a2a-registry/
├── backend/          # FastAPI application + MCP server
│   ├── app/          # API routes, models, repositories, MCP
│   ├── migrations/   # Database schema
│   └── worker.py     # Health check background service
├── website/          # React frontend
├── client-python/    # Python SDK (published to PyPI)
├── hello-world-agent/ # Example A2A agent (Cloudflare Worker)
├── helm/             # Kubernetes deployment charts
└── .github/          # CI/CD workflows

Development

Local Setup

docker-compose up
# API: http://localhost:8000
# Frontend: http://localhost:5173

Backend

cd backend
uv run uvicorn app.main:app --reload

Frontend

cd website
npm install && npm run dev

Contributing

• Register your agent — use the API above
• Report issues — GitHub Issues
• Improve the code — PRs welcome for backend, frontend, and infra

Links

• Website: a2aregistry.org
• API Docs: a2aregistry.org/api/docs
• MCP Server: a2aregistry.org/mcp/
• A2A Protocol: a2a-protocol.org
• Python Client: PyPI

License

MIT