A2A Agent Registry On Aws

What is the A2A Agent Registry?

The A2A Agent Registry is a centralized service for registering, discovering, and managing AI agents in multi-agent systems. It stores AgentCards — the standard metadata format that describes an agent's identity, capabilities, and endpoint. It implements Google's Agent-to-Agent (A2A) protocol to enable seamless agent-to-agent communication and discovery.

Build your own agent marketplace, agentic AI platform, or LLM agent orchestration layer with:

• Semantic search — Find agents using natural language queries (not just keyword matching)
• Skill-based filtering — Query agents by capabilities using metadata filters
• Serverless architecture — Pay only for what you use with AWS Lambda and S3 Vectors
• Python SDK — Python client with retry logic, error handling, and IAM auth

Perfect for teams building multi-agent systems, AI agent orchestration, agentic workflows, or autonomous agent platforms.

🎯 Use Cases

🔖 Features

🎬 Web UI Demo

The demo showcases:

• Register new agent — Add agents with their capabilities and skills
• See all agents — Browse the complete list of registered agents
• Search with plain text — Find agents using natural language queries
• Search by skill name — Filter agents by specific skills

🏗️ Architecture

When you deploy AgentRegistryStack, you get an out-of-the-box agent registry:

The Python SDK (client/) provides a client library with retry logic and IAM authentication.

Optionally, deploy AgentRegistryWebUI for a React-based web interface with Cognito authentication — connect it to your SSO provider or invite users directly from the Cognito console using their email address.

🚀 Quick Start

Prerequisites

• AWS CLI configured with appropriate permissions
• Node.js 18+
• Python 3.11+
• Docker (required by CDK to build Lambda and install dependencies)

Deploy the Agent Registry

# Build the Web UI first (required for deployment)
cd web-ui
npm install
npm run build

# Deploy the infrastructure
cd ../infrastructure
npm install
cdk deploy AgentRegistryStack

Deploy Web UI (Optional)

cd infrastructure
cdk deploy AgentRegistryWebUI

The Web UI stack deploys:

• S3 bucket for static hosting
• CloudFront distribution
• Cognito User Pool for authentication
• Cognito Identity Pool for AWS credentials

Adding Users to the Web UI

Self-signup is disabled for security. To add users, use the CognitoUserPoolConsoleUrl output from the stack deployment — it links directly to the Cognito User Pool console where you can create users:

1. Click the URL from the stack output
2. Click "Create user"
3. Enter the user's email and set a temporary password
4. The user will receive an email to set their permanent password on first login

Important: CORS Configuration

By default, the API allows cross-origin requests from any origin (*). You can restrict CORS to a specific domain by passing the corsOrigin parameter.

To restrict CORS to a specific origin:

# Using a custom domain
cdk deploy AgentRegistryStack -c corsOrigin=https://your-domain.com

# Using the Web UI CloudFront domain (get from AgentRegistryWebUI stack output)
cdk deploy AgentRegistryStack -c corsOrigin=https://d1234567890.cloudfront.net

To restrict CORS to only the Web UI:

1. Deploy AgentRegistryStack first
2. Deploy AgentRegistryWebUI and note the CloudFrontDomainName output
3. Update AgentRegistryStack with -c corsOrigin=<CloudFrontDomainName> to restrict CORS to only the Web UI

Use the Python SDK

from agent_registry_client import AgentRegistryClient
from a2a.types import AgentCard

client = AgentRegistryClient(api_gateway_url="https://your-api.execute-api.region.amazonaws.com/prod")

# Register an agent
agent_id = client.create_agent(AgentCard(
    name="My Agent",
    description="An agent that helps with tasks",
    version="1.0.0",
    url="https://my-agent.example.com"
))

# Search for agents using natural language
results = client.search_agents(query="help with financial analysis")

# Search by skills
results = client.search_agents(skills=["python", "data-analysis"])

# Combined semantic + skill search
results = client.search_agents(query="code review assistant", skills=["python"])

📚 Documentation

💰 Cost Estimate

The serverless architecture means you only pay for what you use. For 1 million requests per month (20% add agent card, 80% search agent cards) in us-east-1:

❓ FAQ

When you register an agent, the registry generates a 1024-dimensional vector embedding from the agent's name and description using Amazon Bedrock Titan Text Embeddings V2. When you search, your query is converted to an embedding, and S3 Vectors finds agents with the most similar embeddings using cosine distance. Results are ranked by similarity score (1 - distance).

Semantic search finds agents based on meaning — "financial advisor" would match an agent described as "investment portfolio manager". Skill filtering is exact matching on declared skills — searching for skill "python" only returns agents that explicitly list "python" as a skill. You can combine both for precise results.

Yes! The registry is framework-agnostic. Any agent that can be described with a name, description, URL, and skills can be registered. The A2A protocol provides a standard way for agents to advertise their capabilities regardless of how they're implemented.

All API endpoints use AWS IAM authentication (Signature Version 4). The Python SDK handles this automatically using your configured AWS credentials. For the Web UI, Cognito provides user authentication and vends temporary AWS credentials.

🤝 Contributing

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

• 🐛 Report bugs
• 💡 Request features
• 🔧 Submit pull requests

📄 License

This project is licensed under the Apache 2.0 License. See LICENSE for details.