Skip to content

c-daniele/agent-reg

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
backend/app
backend/app
 
 
frontend
frontend
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

Agent-Reg: A2A Registry Platform

A comprehensive centralized registry for Agent2Agent (A2A) protocol compliant agents, providing discovery, management, and invocation services for AI agents.

🏗️ Architecture Overview

Agent-Reg is built as a modern full-stack application with two main components:

Backend (FastAPI)

  • Framework: FastAPI with Python 3.8+
  • Database: SQLite with JSON Extension
  • Schema Validation: A2A protocol compliance using JSON Schema
  • API Standard: RESTful API following OpenAPI 3.0 specification

Frontend (React)

  • Framework: React 18+ with TypeScript
  • Styling: Tailwind CSS
  • HTTP Client: Axios
  • UI Components: Headless UI components

🖥️ System Architecture

graph TB
    subgraph "Client Layer"
        UI[React Frontend]
        CLI[CLI Tools]
        EXT[External Clients]
    end
    
    subgraph "API Layer"
        GATEWAY[FastAPI Gateway]
        CORS[CORS Middleware]
        VALID[Schema Validator]
    end
    
    subgraph "Business Layer"
        REG[Agent Registry Service]
        HEART[Heartbeat Manager]
        SEARCH[Search & Filter Engine]
    end
    
    subgraph "Data Layer"
        DB[(SQLite with JSON Extension)]
        SCHEMA[A2A JSON Schema]
    end
    
    UI --> GATEWAY
    CLI --> GATEWAY
    EXT --> GATEWAY
    
    GATEWAY --> CORS
    CORS --> VALID
    VALID --> REG
    
    REG --> HEART
    REG --> SEARCH
    
    REG --> DB
    VALID --> SCHEMA
Loading

Agent Registration Workflow

sequenceDiagram
    participant Client
    participant API
    participant Validator
    participant Registry
    participant Database
    
    Client->>API: POST /agents/register
    API->>Validator: Validate Agent Card
    Validator->>Validator: Check A2A Schema Compliance
    
    alt Valid Agent Card
        Validator-->>API: Valid ✓
        API->>Registry: Store Agent
        Registry->>Registry: Generate UUID
        Registry->>Registry: Add Timestamps
        Registry->>Database: Insert Agent Document
        Database-->>Registry: Confirmation
        Registry-->>API: Agent Record
        API-->>Client: 201 Created + Agent Data
    else Invalid Agent Card
        Validator-->>API: Validation Errors
        API-->>Client: 422 Unprocessable Entity
    end
Loading

🔍 Agent Discovery & Search

graph LR
    subgraph "Search Filters"
        NAME[Name Filter]
        SKILL[Skill Filter]
        CAP[Capabilities Filter]
        OWNER[Owner Filter]
        ALIVE[Liveness Filter]
    end
    
    subgraph "Search Engine"
        FILTER[Filter Logic]
        HEART[Heartbeat Check]
        SORT[Result Sorting]
    end
    
    subgraph "Results"
        LIST[Agent List]
        META[Metadata]
        COUNT[Total Count]
    end
    
    NAME --> FILTER
    SKILL --> FILTER
    CAP --> FILTER
    OWNER --> FILTER
    ALIVE --> HEART
    
    FILTER --> SORT
    HEART --> SORT
    
    SORT --> LIST
    SORT --> META
    SORT --> COUNT
Loading

🗂️ Data Models

Agent Card Schema (A2A Compliant)

classDiagram
    class AgentCard {
        +string name
        +string description
        +string version
        +string protocolVersion
        +string url
        +AgentSkill[] skills
        +AgentCapabilities capabilities
        +string[] defaultInputModes
        +string[] defaultOutputModes
        +string preferredTransport
        +AgentProvider provider
        +string documentationUrl
        +string iconUrl
        +AgentInterface[] additionalInterfaces
        +SecurityRequirement[] security
        +SecuritySchemes securitySchemes
        +AgentCardSignature[] signatures
        +boolean supportsAuthenticatedExtendedCard
    }
    
    class AgentSkill {
        +string id
        +string name
        +string description
        +string[] tags
        +string[] examples
        +string[] inputModes
        +string[] outputModes
        +SecurityRequirement[] security
    }
    
    class AgentCapabilities {
        +boolean streaming
        +boolean stateTransitionHistory
        +boolean pushNotifications
        +AgentExtension[] extensions
    }
    
    class AgentProvider {
        +string organization
        +string url
    }
    
    AgentCard "1" --> "0..*" AgentSkill : contains
    AgentCard "1" --> "1" AgentCapabilities : has
    AgentCard "1" --> "0..1" AgentProvider : provided by
Loading

🏗️ Core Features

Agent Management

  • Registration: Add new A2A compliant agents to the registry
  • Discovery: Search and filter agents by multiple criteria
  • Lifecycle: Update agent information and manage liveness
  • Removal: Delete agents from the registry

A2A Protocol Compliance

  • Schema Validation: Enforce A2A Agent Card schema compliance
  • Protocol Support: Support for JSON-RPC, gRPC, and HTTP+JSON transports
  • Security: Support for various authentication schemes (OAuth2, API Keys, mTLS)
  • Extensions: Handle protocol extensions and custom capabilities

Advanced Search & Filtering

  • Multi-criteria Search: Filter by name, skills, capabilities, owner
  • Liveness Monitoring: Track agent availability via heartbeat mechanism
  • Capability-based Discovery: Find agents by specific capabilities
  • Tag-based Search: Discover agents using skill tags

🗂️ Project Structure

agent-reg/
  backend/                    # FastAPI Backend
    app/
      src/
        main.py                    # FastAPI application entry point
        agent_card_models.py       # Pydantic models for A2A schema
        agent_card_validator.py    # Schema validation logic
        a2a_agent_card_schema.json # A2A JSON Schema definition
      resources/
        sample_cards/              # Example agent cards
      test/                        # API test scripts
      requirements.txt             # Python dependencies

  frontend/                   # React Frontend
    src/
      components/                    # React components
        AgentCard.tsx             # Individual agent display
        AgentFilters.tsx          # Search and filter UI
        AddAgentModal.tsx         # Agent registration form
        Layout.tsx                # Application layout
      services/
        api.ts                    # API client service
      types/
        agent.ts                  # TypeScript type definitions
      App.tsx                     # Main application component
    package.json                  # Node.js dependencies
    tailwind.config.js            # Tailwind CSS configuration

  README.md                   # This documentation

API Endpoints

Agent Management

Method Endpoint Description Request Body Response
POST /agents/register Register a new agent AgentCard Agent
GET /agents List and search agents Query params Agent[]
GET /agents/{id} Get specific agent - Agent
PUT /agents/{id} Update agent AgentUpdate Agent
DELETE /agents/{id} Delete agent - 204 No Content

Agent Operations

Method Endpoint Description Response
POST /agents/{id}/heartbeat Update agent liveness Agent
GET /agents/{id}/invoke_url Get invocation details AgentInvokeResponse

System Health

Method Endpoint Description Response
GET /health System health check HealthResponse

Query Parameters for Agent Search

Parameter Type Description
name string Filter by agent name (case-insensitive)
skill string Filter by specific skill ID
owner string Filter by agent owner
capabilities string Comma-separated list of required capabilities
only_alive boolean Show only agents with recent heartbeat (last 5 minutes)

⚡ Quick Start

Prerequisites

  • Backend: Python 3.8+, pip
  • Frontend: Node.js 16+, npm/yarn
  • Database: No additional setup required (uses file-based SQLite with JSON extension)

Backend Setup

cd backend/app
pip install -r requirements.txt
python src/main.py

The API will be available at http://localhost:8000

Frontend Setup

cd frontend
npm install
npm start

The web interface will be available at http://localhost:3000

🚦 Usage Examples

Register an Agent

curl -X POST "http://localhost:8000/agents/register" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GeoSpatial Route Planner Agent",
    "description": "Provides advanced route planning services",
    "version": "1.2.0",
    "protocolVersion": "0.3.0",
    "url": "https://georoute-agent.example.com/a2a/v1",
    "capabilities": {
      "streaming": true,
      "pushNotifications": true,
      "stateTransitionHistory": false
    },
    "defaultInputModes": ["application/json", "text/plain"],
    "defaultOutputModes": ["application/json", "image/png"],
    "skills": [
      {
        "id": "route-optimizer-traffic",
        "name": "Traffic-Aware Route Optimizer",
        "description": "Calculates optimal routes considering real-time traffic",
        "tags": ["maps", "routing", "navigation", "traffic"]
      }
    ]
  }'

Search for Agents

# Find all agents with streaming capability
curl "http://localhost:8000/agents?capabilities=streaming"

# Find agents by skill
curl "http://localhost:8000/agents?skill=route-optimizer-traffic"

# Find only active agents
curl "http://localhost:8000/agents?only_alive=true"

Agent Heartbeat

curl -X POST "http://localhost:8000/agents/{agent-id}/heartbeat"

🛠️ Configuration

Environment Variables

Backend

  • DATABASE_PATH: Path to the SQLite database file (default: agent_reg.db)

Frontend

  • REACT_APP_API_URL: Backend API URL (default: http://localhost:8000)

🧪 Testing

Backend API Testing

Test scripts are provided in backend/app/test/:

cd backend/app/test
# Register an agent
./01.register.sh

# List agents
./02.list_agents.sh

# Update heartbeat
./03.agent_heartbeat.sh

# Delete agent
./04.agent_delete.sh

Frontend Testing

cd frontend
npm test

🛡️ Security

A2A Protocol Security Features

  • Authentication: Support for OAuth2, OpenID Connect, API Keys, mTLS
  • Authorization: Fine-grained security requirements per agent and skill
  • Signature Verification: JSON Web Signature (JWS) support for agent cards
  • Transport Security: HTTPS enforcement for production environments

Input Validation

  • Schema Validation: All agent cards validated against A2A JSON Schema
  • Data Sanitization: Input data sanitized to prevent injection attacks
  • CORS Policy: Configurable CORS middleware for cross-origin requests

📈 Monitoring & Observability

Health Monitoring

  • Health Check Endpoint: /health provides system status
  • Agent Liveness: Heartbeat mechanism tracks agent availability

Logging

  • Structured Logging: JSON format logs for better parsing
  • Request Tracing: HTTP request/response logging
  • Error Handling: Comprehensive error reporting

🚀 Deployment

Production Deployment

  1. Backend Deployment:

    pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000

  2. Frontend Deployment:

    npm run build
# Serve static files with nginx/Apache

Docker Deployment

# Backend Dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY src/ .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
# Frontend Dockerfile
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
FROM nginx:alpine
COPY --from=0 /app/build /usr/share/nginx/html

🤝 Contributing

Development Setup

  1. Clone Repository:

    git clone <repository-url>
cd agent-reg

  2. Backend Development:

    cd backend/app
pip install -r requirements.txt
python src/main.py

  3. Frontend Development:

    cd frontend
npm install
npm start

Code Quality

  • Backend: Follow PEP 8 Python style guidelines
  • Frontend: Use ESLint and Prettier for code formatting
  • Testing: Maintain test coverage for new features
  • Documentation: Update README for any architectural changes

📚 References

📝 License

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

🆘 Support

For issues, questions, or contributions, please:

  1. Check existing issues in the repository
  2. Create a new issue with detailed description
  3. Follow the contribution guidelines for pull requests

Agent-Reg - Empowering AI Agent Discovery and Collaboration through the Agent2Agent Protocol

About

An A2A compliant Agent Registry

Resources

Readme

License

MIT license
Activity

Stars

3 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages