Getting Started

1Clone the repository

$ git clone https://github.com/prassanna-ravishankar/a2a-registry

2Navigate to the project

$ cd a2a-registry

3Install dependencies

$ pip install -r requirements.txt

4Run the agent

$ python main.py

Or connect to the hosted endpoint: https://a2aregistry.org/

README

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

Capabilities

StreamingPush NotificationsMulti-TurnAuth: none

View on GitHub