{"id":51667905,"url":"https://github.com/OyadotAI/A2ARegistry","last_synced_at":"2026-08-03T02:00:36.770Z","repository":{"id":315271828,"uuid":"1058046830","full_name":"OyadotAI/A2ARegistry","owner":"OyadotAI","description":"A2A Registry ","archived":false,"fork":false,"pushed_at":"2026-03-09T09:21:59.000Z","size":15446,"stargazers_count":17,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T02:10:45.651Z","etag":null,"topics":["a2a-client","a2a-protocol","a2a-re","a2a-server"],"latest_commit_sha":null,"homepage":"https://a2areg.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OyadotAI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["a2aproject"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2025-09-16T14:50:14.000Z","updated_at":"2026-04-27T21:54:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"db8c7a00-dcf1-42c2-ad4e-e8cc014e232d","html_url":"https://github.com/OyadotAI/A2ARegistry","commit_stats":null,"previous_names":["a2areg/a2a-registry","a2abaseai/a2aregistry","oyadotai/a2aregistry"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/OyadotAI/A2ARegistry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OyadotAI%2FA2ARegistry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OyadotAI%2FA2ARegistry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OyadotAI%2FA2ARegistry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OyadotAI%2FA2ARegistry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OyadotAI","download_url":"https://codeload.github.com/OyadotAI/A2ARegistry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OyadotAI%2FA2ARegistry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36214553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-03T02:00:06.975Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a-client","a2a-protocol","a2a-re","a2a-server"],"created_at":"2026-07-14T22:00:19.516Z","updated_at":"2026-08-03T02:00:36.761Z","avatar_url":"https://github.com/OyadotAI.png","language":"Python","funding_links":["https://github.com/sponsors/a2aproject"],"categories":["🛠️ Tools \u0026 Utilities"],"sub_categories":[],"readme":"# A2A Agent Registry\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com/)\n[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)\n[![Production Ready](https://img.shields.io/badge/Production-Ready-green.svg)](PRODUCTION.md)\n\nA centralized registry service for discovering and managing AI agents in the A2A (Agent-to-Agent) ecosystem. This implementation follows the [A2A Agent Registry Proposal](https://github.com/a2aproject/A2A/discussions/741) and provides a complete solution for agent discovery, entitlements, and federation.\n\n## 🌟 Features\n\n- **🎨 Modern Web UI**: Beautiful, responsive React frontend with Tailwind CSS\n- **🔍 Agent Discovery**: Advanced search with lexical and semantic capabilities\n- **🔐 Enterprise Security**: OAuth 2.0, rate limiting, and comprehensive security headers\n- **🌐 Federation**: Cross-registry peering and synchronization\n- **📊 Production Ready**: Monitoring, logging, caching, and automated deployment\n- **🚀 High Performance**: Redis caching, connection pooling, and horizontal scaling\n- **📚 Well-Documented**: Complete API documentation and deployment guides\n\n## Core Quick Start (no frontend)\n\nThis repository is now a core-only API service (no React UI). Use the steps below for a minimal local run:\n\n1. Start dependencies and API\n   ```bash\n   docker-compose up -d db redis opensearch registry\n   ```\n\n2. Apply migrations\n   ```bash\n   alembic upgrade head\n   ```\n\n3. Publish an agent card by URL (Administrator/CatalogManager token required)\n   ```bash\n   curl -X POST \"http://localhost:8000/agents/publish\" \\\n     -H \"Authorization: Bearer YOUR_TOKEN\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"cardUrl\": \"https://example.com/.well-known/agent-card.json\",\n       \"public\": true\n     }'\n   ```\n\n4. Query public/entitled/search endpoints\n   ```bash\n   curl \"http://localhost:8000/agents/public?top=20\u0026skip=0\"\n   curl -H \"Authorization: Bearer YOUR_TOKEN\" \"http://localhost:8000/agents/entitled?top=20\u0026skip=0\"\n   curl -X POST -H \"Authorization: Bearer YOUR_TOKEN\" -H \"Content-Type: application/json\" \\\n     \"http://localhost:8000/agents/search\" -d '{\"q\":\"payments\",\"top\":20,\"skip\":0}'\n   ```\n\nAuthentication: Provide an OAuth2 client-credentials JWT issued by your IdP. JWKS verification is configured via settings.\n\nSLOs: p95 \u003c 200 ms for cache-warm reads (local region), 99.9% availability, scale targets 10M agents / 2k RPS reads / 200 RPS writes.\n\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Python 3.9+\n- Node.js 18+\n- Docker and Docker Compose\n- PostgreSQL 12+\n- Redis 6+\n- OpenSearch 2.x\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/A2AReg/a2a-registry.git\n   cd a2a-registry\n   ```\n\n2. **Start with Docker (Recommended)**\n   ```bash\n   docker-compose up -d\n   ```\n\n3. **Initialize sample data**\n   ```bash\n   python scripts/init_db.py\n   ```\n\n4. **Access the registry**\n   - **Web UI**: http://localhost:3000 (React frontend)\n   - **API**: http://localhost:8000 (FastAPI backend)\n   - **API Docs**: http://localhost:8000/docs\n   - **Health**: http://localhost:8000/health\n\n### Manual Installation\n\n1. **Install backend dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n2. **Install frontend dependencies**\n   ```bash\n   cd frontend\n   npm install --legacy-peer-deps\n   cd ..\n   ```\n\n3. **Configure environment**\n   ```bash\n   cp env.example .env\n   # Edit .env with your configuration\n   ```\n\n4. **Start services**\n   ```bash\n   docker-compose up -d db redis opensearch\n   ```\n\n5. **Run migrations**\n   ```bash\n   alembic upgrade head\n   ```\n\n6. **Start the backend**\n   ```bash\n   python -m registry.main\n   ```\n\n7. **Start the frontend** (in a new terminal)\n   ```bash\n   cd frontend\n   npm run dev\n   ```\n\n## 🎨 Web Interface\n\nThe A2A Agent Registry includes a modern, responsive web interface built with React and Tailwind CSS:\n\n### Key Features\n- **📊 Dashboard**: Overview of registry statistics and system health\n- **🤖 Agent Management**: Browse, search, and manage agents with advanced filtering\n- **👥 Client Management**: OAuth client registration and entitlement management\n- **🌐 Federation**: Configure peer registries and cross-registry synchronization\n- **⚙️ Settings**: System configuration and user preferences\n- **🔐 Authentication**: Secure OAuth 2.0 login with client credentials\n\n### UI Components\n- **Responsive Design**: Works on desktop, tablet, and mobile devices\n- **Dark/Light Mode**: Automatic theme switching based on system preferences\n- **Real-time Updates**: Live data refresh and notifications\n- **Advanced Search**: Semantic and lexical search with filters\n- **Interactive Charts**: Visual representation of registry statistics\n\n## 📖 Documentation\n\n- **[Production Deployment](PRODUCTION.md)** - Enterprise deployment guide\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project\n- **[Security Policy](SECURITY.md)** - Security guidelines and vulnerability reporting\n- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines\n- **[API Documentation](http://localhost:8000/docs)** - Interactive API docs\n- **[Changelog](CHANGELOG.md)** - Release history and changes\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Application\nAPP_NAME=\"A2A Agent Registry\"\nAPP_VERSION=\"1.0.0\"\nDEBUG=false\n\n# Database\nDATABASE_URL=\"postgresql://user:password@localhost:5432/a2a_registry\"\n\n# Redis\nREDIS_URL=\"redis://localhost:6379/0\"\n\n# OpenSearch\nELASTICSEARCH_URL=\"http://localhost:9200\"\nELASTICSEARCH_INDEX=\"a2a_agents\"\n\n# Security\nSECRET_KEY=\"your-secret-key-change-in-production\"\nALGORITHM=\"HS256\"\nACCESS_TOKEN_EXPIRE_MINUTES=30\n\n# Registry\nREGISTRY_BASE_URL=\"http://localhost:8000\"\nMAX_AGENTS_PER_CLIENT=1000\nENABLE_FEDERATION=true\n```\n\n## API Usage\n\n### Authentication\n\nThe registry uses OAuth 2.0 Client Credentials flow for authentication:\n\n```bash\n# Get access token\ncurl -X POST \"http://localhost:8000/oauth/token\" \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"username=your_client_id\u0026password=your_client_secret\"\n```\n\n### Agent Management\n\n#### Register an Agent\n```bash\ncurl -X POST \"http://localhost:8000/agents\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"agent_card\": {\n      \"id\": \"my-agent\",\n      \"name\": \"My AI Agent\",\n      \"version\": \"1.0.0\",\n      \"description\": \"A sample AI agent\",\n      \"capabilities\": {\n        \"a2a_version\": \"1.0\",\n        \"supported_protocols\": [\"http\", \"grpc\"]\n      },\n      \"skills\": {\n        \"input_schema\": {\"type\": \"object\"},\n        \"output_schema\": {\"type\": \"object\"}\n      },\n      \"auth_schemes\": [\n        {\n          \"type\": \"apiKey\",\n          \"location\": \"header\",\n          \"name\": \"X-API-Key\"\n        }\n      ],\n      \"provider\": \"My Company\",\n      \"tags\": [\"ai\", \"assistant\"],\n      \"location\": {\n        \"url\": \"https://my-agent.example.com/.well-known/agent.json\",\n        \"type\": \"agent_card\"\n      }\n    },\n    \"is_public\": true\n  }'\n```\n\n#### Search Agents\n```bash\ncurl -X POST \"http://localhost:8000/agents/search\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"AI assistant\",\n    \"filters\": {\n      \"provider\": \"My Company\",\n      \"tags\": [\"ai\"]\n    },\n    \"top\": 10\n  }'\n```\n\n#### Get Entitled Agents\n```bash\ncurl -X GET \"http://localhost:8000/agents/entitled\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n### Well-Known Endpoints\n\n#### Agent Discovery\n```bash\n# Get agents index\ncurl \"http://localhost:8000/.well-known/agents/index.json\"\n\n# Get specific agent card\ncurl \"http://localhost:8000/agents/my-agent/card\"\n```\n\n## Agent Card Schema\n\nThe Agent Card is the core data structure for agent metadata:\n\n```json\n{\n  \"id\": \"agent-id\",\n  \"name\": \"Agent Name\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Agent description\",\n  \"capabilities\": {\n    \"a2a_version\": \"1.0\",\n    \"supported_protocols\": [\"http\", \"grpc\", \"websocket\"],\n    \"max_concurrent_requests\": 100,\n    \"timeout_seconds\": 30,\n    \"rate_limit_per_minute\": 1000\n  },\n  \"skills\": {\n    \"input_schema\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"query\": {\"type\": \"string\"},\n        \"context\": {\"type\": \"object\"}\n      }\n    },\n    \"output_schema\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"response\": {\"type\": \"string\"},\n        \"confidence\": {\"type\": \"number\"}\n      }\n    }\n  },\n  \"auth_schemes\": [\n    {\n      \"type\": \"apiKey\",\n      \"location\": \"header\",\n      \"name\": \"X-API-Key\"\n    },\n    {\n      \"type\": \"oauth2\",\n      \"flow\": \"client_credentials\",\n      \"token_url\": \"https://auth.example.com/oauth/token\",\n      \"scopes\": [\"agent:read\", \"agent:write\"]\n    }\n  ],\n  \"tee_details\": {\n    \"enabled\": true,\n    \"provider\": \"Intel SGX\",\n    \"attestation\": \"required\",\n    \"version\": \"2.0\"\n  },\n  \"provider\": \"Agent Provider\",\n  \"tags\": [\"ai\", \"assistant\", \"nlp\"],\n  \"contact_url\": \"https://example.com/contact\",\n  \"documentation_url\": \"https://docs.example.com/agent\",\n  \"location\": {\n    \"url\": \"https://agent.example.com/.well-known/agent.json\",\n    \"type\": \"agent_card\"\n  }\n}\n```\n\n## Federation\n\nThe registry supports federation with other A2A registries:\n\n### Add a Peer Registry\n```bash\ncurl -X POST \"http://localhost:8000/peers\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Partner Registry\",\n    \"base_url\": \"https://partner-registry.example.com\",\n    \"description\": \"Partner organization registry\",\n    \"auth_token\": \"peer_auth_token\",\n    \"sync_enabled\": true,\n    \"sync_interval_minutes\": 60\n  }'\n```\n\n### Synchronize with Peers\n```bash\n# Sync specific peer\ncurl -X POST \"http://localhost:8000/peers/peer-id/sync\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Sync all peers\ncurl -X POST \"http://localhost:8000/peers/sync-all\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n## Development\n\n### Quality Checks\nRun comprehensive quality checks using the provided scripts:\n\n```bash\n# Python script (recommended)\npython quality_check.py --all\n\n# Shell script\n./quality_check.sh --all\n\n# Makefile\nmake quality\n\n# Individual checks\npython quality_check.py --lint --test\nmake lint test\n\n# Development commands\nmake backend                    # Run the backend server\nmake examples                   # Run all examples\nmake example NAME=basic_usage   # Run specific example\n\n# Publishing commands\nmake publish                    # Publish SDK to PyPI\nmake build-sdk                  # Build SDK package\nmake test-sdk                   # Test SDK package locally\n```\n\nSee [QUALITY_CHECKS.md](QUALITY_CHECKS.md) for detailed information.\n\n### Running Tests\n```bash\npytest tests/\n```\n\n### Code Formatting\n```bash\nblack app/\nisort app/\n```\n\n### Database Migrations\n```bash\n# Create migration\nalembic revision --autogenerate -m \"Description\"\n\n# Apply migration\nalembic upgrade head\n```\n\n## Architecture\n\n### Frontend (React + TypeScript + Vite)\n- **Framework**: React 18 with TypeScript\n- **Build Tool**: Vite for fast development and optimized builds\n- **Styling**: Tailwind CSS with custom components\n- **State Management**: React Query for server state management\n- **Routing**: React Router for SPA navigation\n- **Forms**: React Hook Form with validation\n- **Notifications**: React Hot Toast for user feedback\n\n### Backend Components\n\n1. **API Layer**: FastAPI-based REST API with OpenAPI documentation\n2. **Service Layer**: Business logic for agents, clients, search, and peering\n3. **Data Layer**: SQLAlchemy ORM with PostgreSQL backend\n4. **Search Layer**: OpenSearch for high-performance search\n5. **Auth Layer**: OAuth 2.0 with JWT tokens\n6. **Federation Layer**: Peer-to-peer synchronization\n7. **Web Interface**: Modern React frontend with responsive design\n\n### Database Schema\n\n- **agents**: Agent metadata and cards\n- **clients**: OAuth 2.0 clients\n- **client_entitlements**: Agent access permissions\n- **peer_registries**: Federation peers\n- **peer_syncs**: Synchronization history\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## License\n\nApache 2.0 License - see LICENSE file for details.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Ways to Contribute\n\n- 🐛 **Report bugs** using GitHub Issues\n- 💡 **Suggest features** using GitHub Discussions\n- 📝 **Improve documentation**\n- 🔧 **Submit pull requests**\n- 🧪 **Add tests**\n- 🔒 **Security improvements**\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🛡️ Security\n\nSecurity is important to us. Please report security vulnerabilities privately to security@a2areg.dev.\n\nSee our [Security Policy](SECURITY.md) for more information.\n\n## 🌍 Community\n\n- **💬 Discord**: [Join our community chat](https://discord.gg/rpe5nMSumw) - Get help, share ideas, and connect with other developers\n- **🐛 GitHub Issues**: [Report bugs and request features](https://github.com/A2AReg/a2a-registry/issues)\n- **💡 GitHub Discussions**: [Community discussions](https://github.com/A2AReg/a2a-registry/discussions)\n- **🤖 A2A Community**: [A2A Discussions](https://github.com/A2AReg/A2A/discussions)\n- **📚 Documentation**: [Full API documentation](http://localhost:8000/docs)\n\n## 🙏 Acknowledgments\n\n- [A2A Project](https://github.com/a2aproject/A2A) for the original proposal\n- [FastAPI](https://fastapi.tiangolo.com/) for the excellent web framework\n- [SQLAlchemy](https://www.sqlalchemy.org/) for database ORM\n- [OpenSearch](https://opensearch.org/) for search capabilities\n- All contributors and the open source community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOyadotAI%2FA2ARegistry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOyadotAI%2FA2ARegistry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOyadotAI%2FA2ARegistry/lists"}