A2A Agent Registry

A centralized registry service for discovering and managing AI agents in the A2A (Agent-to-Agent) ecosystem. This implementation follows the A2A Agent Registry Proposal and provides a complete solution for agent discovery, entitlements, and federation.

🌟 Features

• 🎨 Modern Web UI: Beautiful, responsive React frontend with Tailwind CSS
• 🔍 Agent Discovery: Advanced search with lexical and semantic capabilities
• 🔐 Enterprise Security: OAuth 2.0, rate limiting, and comprehensive security headers
• 🌐 Federation: Cross-registry peering and synchronization
• 📊 Production Ready: Monitoring, logging, caching, and automated deployment
• 🚀 High Performance: Redis caching, connection pooling, and horizontal scaling
• 📚 Well-Documented: Complete API documentation and deployment guides

Core Quick Start (no frontend)

This repository is now a core-only API service (no React UI). Use the steps below for a minimal local run:

1. Start dependencies and API

   docker-compose up -d db redis opensearch registry

2. Apply migrations

   alembic upgrade head

3. Publish an agent card by URL (Administrator/CatalogManager token required)

   curl -X POST "http://localhost:8000/agents/publish" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "cardUrl": "https://example.com/.well-known/agent-card.json",
       "public": true
     }'

4. Query public/entitled/search endpoints

   curl "http://localhost:8000/agents/public?top=20&skip=0"
   curl -H "Authorization: Bearer YOUR_TOKEN" "http://localhost:8000/agents/entitled?top=20&skip=0"
   curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
     "http://localhost:8000/agents/search" -d '{"q":"payments","top":20,"skip":0}'

Authentication: Provide an OAuth2 client-credentials JWT issued by your IdP. JWKS verification is configured via settings.

SLOs: p95 < 200 ms for cache-warm reads (local region), 99.9% availability, scale targets 10M agents / 2k RPS reads / 200 RPS writes.

🚀 Quick Start

Prerequisites

• Python 3.9+
• Node.js 18+
• Docker and Docker Compose
• PostgreSQL 12+
• Redis 6+
• OpenSearch 2.x

Installation

1. Clone the repository

   git clone https://github.com/A2AReg/a2a-registry.git
   cd a2a-registry

2. Start with Docker (Recommended)

   docker-compose up -d

3. Initialize sample data

   python scripts/init_db.py

4. Access the registry

   • Web UI: http://localhost:3000 (React frontend)
   • API: http://localhost:8000 (FastAPI backend)
   • API Docs: http://localhost:8000/docs
   • Health: http://localhost:8000/health

Manual Installation

1. Install backend dependencies

   pip install -r requirements.txt

2. Install frontend dependencies

   cd frontend
   npm install --legacy-peer-deps
   cd ..

3. Configure environment

   cp env.example .env
   # Edit .env with your configuration

4. Start services

   docker-compose up -d db redis opensearch

5. Run migrations

   alembic upgrade head

6. Start the backend

   python -m registry.main

7. Start the frontend (in a new terminal)

   cd frontend
   npm run dev

🎨 Web Interface

The A2A Agent Registry includes a modern, responsive web interface built with React and Tailwind CSS:

Key Features

• 📊 Dashboard: Overview of registry statistics and system health
• 🤖 Agent Management: Browse, search, and manage agents with advanced filtering
• 👥 Client Management: OAuth client registration and entitlement management
• 🌐 Federation: Configure peer registries and cross-registry synchronization
• ⚙️ Settings: System configuration and user preferences
• 🔐 Authentication: Secure OAuth 2.0 login with client credentials

UI Components

• Responsive Design: Works on desktop, tablet, and mobile devices
• Dark/Light Mode: Automatic theme switching based on system preferences
• Real-time Updates: Live data refresh and notifications
• Advanced Search: Semantic and lexical search with filters
• Interactive Charts: Visual representation of registry statistics

📖 Documentation

• Production Deployment - Enterprise deployment guide
• Contributing Guide - How to contribute to the project
• Security Policy - Security guidelines and vulnerability reporting
• Code of Conduct - Community guidelines
• API Documentation - Interactive API docs
• Changelog - Release history and changes

Configuration

Environment Variables

# Application
APP_NAME="A2A Agent Registry"
APP_VERSION="1.0.0"
DEBUG=false

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/a2a_registry"

# Redis
REDIS_URL="redis://localhost:6379/0"

# OpenSearch
ELASTICSEARCH_URL="http://localhost:9200"
ELASTICSEARCH_INDEX="a2a_agents"

# Security
SECRET_KEY="your-secret-key-change-in-production"
ALGORITHM="HS256"
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Registry
REGISTRY_BASE_URL="http://localhost:8000"
MAX_AGENTS_PER_CLIENT=1000
ENABLE_FEDERATION=true

API Usage

Authentication

The registry uses OAuth 2.0 Client Credentials flow for authentication:

# Get access token
curl -X POST "http://localhost:8000/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=your_client_id&password=your_client_secret"

Agent Management

Register an Agent

curl -X POST "http://localhost:8000/agents" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_card": {
      "id": "my-agent",
      "name": "My AI Agent",
      "version": "1.0.0",
      "description": "A sample AI agent",
      "capabilities": {
        "a2a_version": "1.0",
        "supported_protocols": ["http", "grpc"]
      },
      "skills": {
        "input_schema": {"type": "object"},
        "output_schema": {"type": "object"}
      },
      "auth_schemes": [
        {
          "type": "apiKey",
          "location": "header",
          "name": "X-API-Key"
        }
      ],
      "provider": "My Company",
      "tags": ["ai", "assistant"],
      "location": {
        "url": "https://my-agent.example.com/.well-known/agent.json",
        "type": "agent_card"
      }
    },
    "is_public": true
  }'

Search Agents

curl -X POST "http://localhost:8000/agents/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI assistant",
    "filters": {
      "provider": "My Company",
      "tags": ["ai"]
    },
    "top": 10
  }'

Get Entitled Agents

curl -X GET "http://localhost:8000/agents/entitled" \
  -H "Authorization: Bearer YOUR_TOKEN"

Well-Known Endpoints

Agent Discovery

# Get agents index
curl "http://localhost:8000/.well-known/agents/index.json"

# Get specific agent card
curl "http://localhost:8000/agents/my-agent/card"

Agent Card Schema

The Agent Card is the core data structure for agent metadata:

{
  "id": "agent-id",
  "name": "Agent Name",
  "version": "1.0.0",
  "description": "Agent description",
  "capabilities": {
    "a2a_version": "1.0",
    "supported_protocols": ["http", "grpc", "websocket"],
    "max_concurrent_requests": 100,
    "timeout_seconds": 30,
    "rate_limit_per_minute": 1000
  },
  "skills": {
    "input_schema": {
      "type": "object",
      "properties": {
        "query": {"type": "string"},
        "context": {"type": "object"}
      }
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "response": {"type": "string"},
        "confidence": {"type": "number"}
      }
    }
  },
  "auth_schemes": [
    {
      "type": "apiKey",
      "location": "header",
      "name": "X-API-Key"
    },
    {
      "type": "oauth2",
      "flow": "client_credentials",
      "token_url": "https://auth.example.com/oauth/token",
      "scopes": ["agent:read", "agent:write"]
    }
  ],
  "tee_details": {
    "enabled": true,
    "provider": "Intel SGX",
    "attestation": "required",
    "version": "2.0"
  },
  "provider": "Agent Provider",
  "tags": ["ai", "assistant", "nlp"],
  "contact_url": "https://example.com/contact",
  "documentation_url": "https://docs.example.com/agent",
  "location": {
    "url": "https://agent.example.com/.well-known/agent.json",
    "type": "agent_card"
  }
}

Federation

The registry supports federation with other A2A registries:

Add a Peer Registry

curl -X POST "http://localhost:8000/peers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partner Registry",
    "base_url": "https://partner-registry.example.com",
    "description": "Partner organization registry",
    "auth_token": "peer_auth_token",
    "sync_enabled": true,
    "sync_interval_minutes": 60
  }'

Synchronize with Peers

# Sync specific peer
curl -X POST "http://localhost:8000/peers/peer-id/sync" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Sync all peers
curl -X POST "http://localhost:8000/peers/sync-all" \
  -H "Authorization: Bearer YOUR_TOKEN"

Development

Quality Checks

Run comprehensive quality checks using the provided scripts:

# Python script (recommended)
python quality_check.py --all

# Shell script
./quality_check.sh --all

# Makefile
make quality

# Individual checks
python quality_check.py --lint --test
make lint test

# Development commands
make backend                    # Run the backend server
make examples                   # Run all examples
make example NAME=basic_usage   # Run specific example

# Publishing commands
make publish                    # Publish SDK to PyPI
make build-sdk                  # Build SDK package
make test-sdk                   # Test SDK package locally

See QUALITY_CHECKS.md for detailed information.

Running Tests

pytest tests/

Code Formatting

black app/
isort app/

Database Migrations

# Create migration
alembic revision --autogenerate -m "Description"

# Apply migration
alembic upgrade head

Architecture

Frontend (React + TypeScript + Vite)

• Framework: React 18 with TypeScript
• Build Tool: Vite for fast development and optimized builds
• Styling: Tailwind CSS with custom components
• State Management: React Query for server state management
• Routing: React Router for SPA navigation
• Forms: React Hook Form with validation
• Notifications: React Hot Toast for user feedback

Backend Components

1. API Layer: FastAPI-based REST API with OpenAPI documentation
2. Service Layer: Business logic for agents, clients, search, and peering
3. Data Layer: SQLAlchemy ORM with PostgreSQL backend
4. Search Layer: OpenSearch for high-performance search
5. Auth Layer: OAuth 2.0 with JWT tokens
6. Federation Layer: Peer-to-peer synchronization
7. Web Interface: Modern React frontend with responsive design

Database Schema

• agents: Agent metadata and cards
• clients: OAuth 2.0 clients
• client_entitlements: Agent access permissions
• peer_registries: Federation peers
• peer_syncs: Synchronization history

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

Apache 2.0 License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Ways to Contribute

• 🐛 Report bugs using GitHub Issues
• 💡 Suggest features using GitHub Discussions
• 📝 Improve documentation
• 🔧 Submit pull requests
• 🧪 Add tests
• 🔒 Security improvements

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🛡️ Security

Security is important to us. Please report security vulnerabilities privately to security@a2areg.dev.

See our Security Policy for more information.

🌍 Community

• 💬 Discord: Join our community chat - Get help, share ideas, and connect with other developers
• 🐛 GitHub Issues: Report bugs and request features
• 💡 GitHub Discussions: Community discussions
• 🤖 A2A Community: A2A Discussions
• 📚 Documentation: Full API documentation

🙏 Acknowledgments

• A2A Project for the original proposal
• FastAPI for the excellent web framework
• SQLAlchemy for database ORM
• OpenSearch for search capabilities
• All contributors and the open source community