A2a catalog closes #298

[crivetimihai]

A2A (Agent-to-Agent) Catalog Implementation

Closes #298

🎯 Overview

Implemented a comprehensive A2A (Agent-to-Agent) catalog system for the MCP Gateway, enabling registration and management of external AI agents (OpenAI, Anthropic, custom) and exposing them as MCP tools for seamless integration.

🚀 Features Implemented

Core Infrastructure

• Database Models: A2AAgent and A2AAgentMetric models with full SQLAlchemy relationships
• Pydantic Schemas: Complete validation schemas (A2AAgentCreate/Update/Read, A2AAgentMetrics, A2AAgentInvocation)
• Service Layer: Full CRUD operations with A2AAgentService including agent invocation and metrics
• Database Migration: Alembic migration for A2A tables and relationships

API Integration

• REST API Endpoints: Complete /a2a API with all CRUD operations:
  • GET/POST /a2a - List and create agents
  • GET/PUT/DELETE /a2a/{agent_id} - Individual agent operations
  • POST /a2a/{agent_id}/toggle - Status management
  • POST /a2a/{agent_name}/invoke - Direct agent invocation
• Metrics Integration: A2A metrics included in /metrics endpoints
• Error Handling: Comprehensive exception handling with custom error types

Admin UI

• Dedicated A2A Tab: Full admin interface for agent management
• Agent Registration Form: Complete form with all configuration options
• Agent List Display: Real-time agent status, metrics, and details
• Test Functionality: Blue "Test" button for each agent with real-time results
• Status Management: Enable/disable and delete functionality with confirmation
• Server-side Rendering: Agents loaded with page for optimal performance

Protocol Support

• Multi-Protocol: Automatic detection of JSONRPC vs custom A2A formats
• JSONRPC Integration: Full support for agents expecting JSONRPC format
• Custom Protocol: Support for proprietary agent communication formats
• Tool Integration: A2A agents can be exposed as MCP tools through virtual servers

Configuration & Security

• Feature Toggles: Complete configuration system with environment variables:
  • MCPGATEWAY_A2A_ENABLED - Master switch
  • MCPGATEWAY_A2A_MAX_AGENTS - Capacity control
  • MCPGATEWAY_A2A_DEFAULT_TIMEOUT - Performance tuning
  • MCPGATEWAY_A2A_MAX_RETRIES - Reliability settings
  • MCPGATEWAY_A2A_METRICS_ENABLED - Observability control
• Conditional Functionality: All A2A features properly gated by configuration
• Security: Encrypted credential storage and configurable authentication

Monitoring & Observability

• Comprehensive Metrics: Track execution count, success rate, response times
• Performance Monitoring: Min/max/average response times and timestamps
• Real-time Status: Agent reachability and health monitoring
• Audit Trail: Complete metadata tracking for creation/modification

Virtual Server Integration

• Association Support: A2A agents can be associated with virtual servers
• Tool Exposure: Agents automatically available as MCP tools when associated
• Schema Integration: Server schemas updated to include associated_a2a_agents
• Auto-tool Creation: Infrastructure for automatic tool generation from agents

🔧 Technical Implementation Details

Database Schema

-- A2A Agents table
CREATE TABLE a2a_agents (
    id VARCHAR(36) PRIMARY KEY,
    name VARCHAR UNIQUE NOT NULL,
    slug VARCHAR UNIQUE NOT NULL,
    description TEXT,
    endpoint_url VARCHAR NOT NULL,
    agent_type VARCHAR DEFAULT 'generic',
    protocol_version VARCHAR DEFAULT '1.0',
    capabilities JSON DEFAULT '{}',
    config JSON DEFAULT '{}',
    auth_type VARCHAR,
    auth_value TEXT,
    enabled BOOLEAN DEFAULT true,
    reachable BOOLEAN DEFAULT true,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    last_interaction TIMESTAMP,
    tags JSON DEFAULT '[]',
    -- Audit metadata
    created_by VARCHAR,
    created_from_ip VARCHAR,
    created_via VARCHAR,
    created_user_agent TEXT,
    modified_by VARCHAR,
    modified_from_ip VARCHAR,
    modified_via VARCHAR,
    modified_user_agent TEXT,
    import_batch_id VARCHAR,
    federation_source VARCHAR,
    version INTEGER DEFAULT 1
);

-- Metrics tracking
CREATE TABLE a2a_agent_metrics (
    id INTEGER PRIMARY KEY,
    a2a_agent_id VARCHAR(36) REFERENCES a2a_agents(id),
    timestamp TIMESTAMP NOT NULL,
    response_time FLOAT NOT NULL,
    is_success BOOLEAN NOT NULL,
    error_message TEXT,
    interaction_type VARCHAR DEFAULT 'invoke'
);

-- Virtual server association
CREATE TABLE server_a2a_association (
    server_id VARCHAR REFERENCES servers(id),
    a2a_agent_id VARCHAR REFERENCES a2a_agents(id),
    PRIMARY KEY (server_id, a2a_agent_id)
);

Key Service Methods

• register_agent() - Register new A2A agent with validation
• list_agents() - List agents with filtering and pagination
• get_agent() / get_agent_by_name() - Retrieve specific agents
• update_agent() - Update agent configuration
• toggle_agent_status() - Enable/disable agents
• delete_agent() - Remove agents
• invoke_agent() - Call external agents with protocol detection
• aggregate_metrics() - Performance metrics aggregation

Protocol Detection Logic

# Format request based on agent type and endpoint
if agent.agent_type in ["generic", "jsonrpc"] or agent.endpoint_url.endswith("/"):
    # Use JSONRPC format for agents that expect it
    request_data = {
        "jsonrpc": "2.0",
        "method": parameters.get("method", "message/send"),
        "params": parameters.get("params", parameters),
        "id": 1
    }
else:
    # Use custom A2A format
    request_data = {
        "interaction_type": interaction_type,
        "parameters": parameters,
        "protocol_version": agent.protocol_version
    }

📁 Files Modified/Created

Core Backend Files

• mcpgateway/db.py - Added A2A database models and relationships
• mcpgateway/schemas.py - Added A2A Pydantic schemas and validation
• mcpgateway/main.py - Added A2A router, service initialization, and metrics integration
• mcpgateway/config.py - Added A2A configuration options
• mcpgateway/services/a2a_service.py - NEW - Complete A2A service implementation
• mcpgateway/services/server_service.py - Added A2A agent association support
• mcpgateway/services/tool_service.py - Added A2A tool creation and invocation support

Admin UI & Frontend

• mcpgateway/admin.py - Added A2A admin routes and handlers
• mcpgateway/templates/admin.html - Added A2A tab, forms, and agent display
• mcpgateway/static/admin.js - Added A2A test functionality and tab support

Database Migration

• mcpgateway/alembic/versions/add_a2a_agents_and_metrics.py - NEW - Database migration

Documentation

• README.md - Added A2A features to overview and API documentation
• CLAUDE.md - Added A2A configuration and usage documentation
• .env.example - Added A2A environment variable examples
• docs/docs/using/agents/a2a.md - NEW - Complete A2A usage guide
• docs/docs/using/agents/index.md - Added A2A integration overview
• docs/docs/overview/tags.md - Added A2A agents to taggable entities

Testing

• tests/unit/mcpgateway/services/test_a2a_service.py - NEW - A2A service tests
• tests/unit/mcpgateway/test_main.py - Updated metrics tests for A2A integration
• tests/e2e/test_admin_apis.py - Updated for A2A environment configuration
• tests/unit/mcpgateway/test_ui_version.py - Updated for A2A compatibility

🧪 Testing & Verification

Manual Testing Verified

• ✅ A2A agent registration via Admin UI (http://localhost:4444/admin#a2a-agents)
• ✅ Agent test button functionality (blue "Test" button working)
• ✅ JSONRPC protocol detection and communication
• ✅ Real agent integration (tested with localhost:9999 Hello World agent)
• ✅ Metrics tracking (execution counts, success rates, timestamps)
• ✅ Configuration toggles (enable/disable A2A features)

API Testing Verified

# Agent registration
curl -X POST "http://localhost:4444/a2a" -H "Authorization: Bearer $TOKEN" -d '{...}'

# Agent invocation  
curl -X POST "http://localhost:4444/a2a/tadsa/invoke" -H "Authorization: Bearer $TOKEN" -d '{...}'

# Admin test endpoint
curl -X POST "http://localhost:4444/admin/a2a/{agent_id}/test" -H "Authorization: Bearer $TOKEN"

# Virtual server with A2A agents
curl -X POST "http://localhost:4444/servers" -H "Authorization: Bearer $TOKEN" -d '{
  "name": "AI Assistant Server",
  "associated_a2a_agents": ["agent-id"]
}'

Test Results

• ✅ Unit Tests: Core functionality verified
• ✅ Service Tests: A2A service operations working
• ✅ Metrics Tests: A2A metrics integration functional
• ✅ Admin UI Tests: Template rendering and functionality working
• ✅ E2E Tests: End-to-end admin UI workflows verified

🔍 Code Quality

Linting & Standards

• ✅ Flake8: All Python linting issues resolved
• ✅ Pylint: Code quality standards met, unused arguments handled
• ✅ Web Linting: HTML/CSS/JS issues fixed (make lint-web passes)
• ✅ Doctests: Server service doctests updated for A2A integration
• ✅ Security: Input validation, authentication, and encryption implemented

Performance Considerations

• ✅ Async Operations: All A2A operations properly async
• ✅ Connection Management: HTTP client connection pooling
• ✅ Timeout Handling: Configurable timeouts for agent calls
• ✅ Retry Logic: Configurable retry attempts for failed calls
• ✅ Metrics Collection: Minimal overhead performance tracking

📊 Real-World Results

Successfully tested with actual A2A agent:

• Agent: "Hello World Agent" at http://localhost:9999
• Protocol: JSONRPC with message/send method
• Response: "Hello World" message successfully received
• Metrics: Executions: 2 | Success Rate: 100.0%
• Admin UI: Test button shows "✅ Test Successful"

🔄 Integration Patterns

A2A Agent as MCP Tool Workflow

1. Register A2A agent via Admin UI or API
2. Associate agent with virtual server
3. MCP clients connect to server
4. Agents appear as discoverable MCP tools
5. Tool invocations route to A2A agents
6. Responses converted to MCP format

Supported Agent Types

• OpenAI-compatible: API key authentication, standard endpoints
• Anthropic-compatible: API key authentication, Claude API format
• JSONRPC Agents: Standard JSONRPC 2.0 protocol
• Custom Agents: Flexible protocol and authentication support

🎛️ Configuration Examples

Environment Variables

# Enable A2A features
MCPGATEWAY_A2A_ENABLED=true

# Performance settings
MCPGATEWAY_A2A_DEFAULT_TIMEOUT=30
MCPGATEWAY_A2A_MAX_RETRIES=3

# Capacity limits
MCPGATEWAY_A2A_MAX_AGENTS=100

# Observability
MCPGATEWAY_A2A_METRICS_ENABLED=true

Agent Configuration

{
  "name": "hello_world_agent",
  "endpoint_url": "http://localhost:9999/",
  "agent_type": "jsonrpc",
  "description": "External AI agent for hello world functionality",
  "auth_type": "api_key",
  "auth_value": "your-api-key",
  "tags": ["ai", "hello-world"],
  "capabilities": {"streaming": true},
  "config": {"max_tokens": 1000, "temperature": 0.7}
}

🎉 Impact & Benefits

For Users

• Simplified Integration: Register any external AI agent with a few clicks
• Universal Access: All agents accessible via standard MCP protocol
• Real-time Testing: Test agent functionality directly from admin UI
• Performance Monitoring: Track agent health and performance metrics
• Flexible Configuration: Fine-grained control over A2A features

For Developers

• Clean Architecture: Well-structured service layer with proper separation of concerns
• Extensible Design: Easy to add new agent types and protocols
• Comprehensive Testing: Full test coverage with real agent verification
• Production Ready: Complete error handling, logging, and monitoring

For Operations

• Feature Toggles: Enable/disable A2A functionality as needed
• Security Controls: Encrypted credential storage and authentication
• Monitoring: Detailed metrics and audit trails
• Scalability: Designed for production deployment with proper resource limits

🔗 Related Issues/Features

This implementation enables:

• Cross-agent communication and tool sharing
• Unified AI agent management interface
• Standardized agent integration patterns
• Multi-protocol agent support
• Centralized monitoring and observability

✅ Acceptance Criteria Met

• A2A agents can be registered via Admin UI
• A2A agents can be registered via REST API
• Agents can be tested with built-in test functionality
• Agents can be associated with virtual servers
• Agents are exposed as MCP tools when associated
• Complete configuration system with feature toggles
• Comprehensive metrics and monitoring
• Full documentation and usage guides
• All tests passing and code quality standards met
• Real-world verification with actual A2A agent

🚀 Ready for Production

The A2A catalog system is fully implemented, tested, and documented. It provides a complete solution for integrating external AI agents into the MCP Gateway ecosystem with enterprise-grade features including security, monitoring, and configuration control.

Status: ✅ COMPLETE AND OPERATIONAL