SUPERVAIZER

A Python toolkit for building, managing, and connecting AI agents with full Agent-to-Agent (A2A) protocol support.

Description

SUPERVAIZER is a toolkit built for the age of AI interoperability. At its core, it implements Google's Agent-to-Agent (A2A) protocol, enabling seamless discovery and interaction between agents across different systems and platforms.

With comprehensive support for the A2A specification, SUPERVAIZER allows you to:

• Enhance the capabilities of your agents, making them automatically discoverable by other A2A systems
• Expose standardized agent capabilities through agent cards
• Monitor agent health and status through dedicated endpoints
• Connect your agents to the growing ecosystem of A2A-compatible tools

Beyond A2A interoperability, SUPERVAIZER provides a robust API for agent registration, job control, event handling, telemetry, and more, making it a crucial component for building and managing AI agent systems.

Features

• Agent Management: Register, update, and control agents
• Job Control: Create, track, and manage jobs
• Event Handling: Process and respond to system events
• Telemetry: Monitor and analyze system performance
• Server Communication: Interact with SUPERVAIZE servers
• Account Management: Manage user accounts and authentication
• A2A Protocol Support: Integration with Google's Agent-to-Agent protocol for interoperability

A2A Protocol Support

SUPERVAIZER implements Google's Agent-to-Agent (A2A) protocol, providing standardized discovery and interaction with agents across different platforms and systems.

Implemented A2A Features

• Agent Discovery: /.well-known/agents.json endpoint for listing all available agents Note: the current version of the A2A protocol does not support yet multiple agents.
• Agent Cards: Detailed agent information available at /.well-known/agents/v{version}/{agent_slug}_agent.json
• Health Monitoring: Real-time system and agent health data at /.well-known/health
• Versioned Endpoints: Support for agent versioning with backward compatibility
• OpenAPI Integration: Direct links to OpenAPI specifications and documentation
• Version Information: Comprehensive version tracking with changelog access

Benefits of A2A Integration

• Interoperability: Your agents can be discovered and used by any A2A-compatible client
• Standardized Interface: Consistent API structure across all agents and platforms
• Self-Documentation: Automatic generation of comprehensive agent cards with capabilities
• Health Insights: Real-time monitoring of agent status and performance metrics
• Future-Proofing: Join the emerging standard for agent interoperability

Example: Discovering Agents

To discover all agents on a SUPERVAIZER instance:

curl https://your-server/.well-known/agents.json

Example: Agent Card

To access a specific agent's capabilities:

curl https://your-server/.well-known/agents/v1.0.0/myagent_agent.json

Future A2A Enhancements

• Webhooks: Event subscription for real-time updates
• Rich Authentication: OAuth2 and API key options with scope control
• Tool Streaming: Support for streaming responses in long-running operations
• Extended Metadata: Licensing, pricing, and usage limit information
• Localization: Multi-language support for agent interfaces

ACP Protocol Support

SUPERVAIZER also implements the Agent Communication Protocol (ACP), providing standardized discovery and interaction with agents according to BeeAI's ACP specification.

Implemented ACP Features

• Agent Discovery: /agents endpoint for listing all available agents
• Agent Details: Detailed agent information available at /agents/{agent_slug}
• Health Monitoring: Real-time system and agent health data at /agents/health
• Agent Metadata: Comprehensive metadata including documentation, language support, authors, and more
• Status Metrics: Performance metrics like success rate and average runtime

Benefits of ACP Integration

• Interoperability: Your agents can be discovered and used by any ACP-compatible client
• Standardized Interface: Consistent API structure across all agents and platforms
• Rich Metadata: Automatically includes comprehensive metadata about agent capabilities
• Health Insights: Real-time monitoring of agent status and performance metrics
• Multi-Protocol Support: Works alongside A2A to provide maximum interoperability

Example: Discovering Agents

To discover all agents on a SUPERVAIZER instance:

curl https://your-server/agents

Example: Agent Detail

To access a specific agent's capabilities:

curl https://your-server/agents/myagent

Installation

pip install supervaizer

Or with development dependencies:

pip install "supervaizer[dev]"

Quick Start

from supervaizer import (
    Server,
    Agent,
    AgentMethod,
    Parameter,
    ParametersSetup,
    AgentMethods,
)
# Define at least one AgentMethod
agent_method = AgentMethod(
    name="start",
    method="example_agent.example_synchronous_job_start", #This is the function that is triggered when agent start
    is_async=False,
    params={"action": "start"},
    fields=[
        {
            "name": "Variable to start agent job",
            "type": str,
            "field_type": "CharField",
            "max_length": 100,
            "required": True,
        }]}

# Define agent parameters (optional)
agent_parameters = ParametersSetup.from_list([
    Parameter(
        name="OPEN_API_KEY",
        description="OpenAPI Key",
        is_environment=True,
    )]),

# Define at least one agent
agent = Agent(
    name="agent_name",
    id="agent_id",
    author="John Doe",
    developer="Developer",
    maintainer="Ive Maintained",
    editor="Yuri Editor",
    version="1.3",
    description="This is a test agent",
    urls={"dev": "http://host.docker.internal:8001", "prod": ""},
    active_environment="dev",
    tags=["testtag", "testtag2"],
    methods=AgentMethods(
        job_start=agent_method,
        job_stop=agent_method, #should be different methods
        job_status=agent_method, # should be different methods
        chat=None,
        custom=None}
    ),
    parameters_setup=agent_parameters,
)

# Initialize a connection to the SUPERVAIZE server
server = Server(agents=[agent],
    acp_endpoints=True,
    a2a_endpoints=True,
    supervisor_account=None,)

# Start the server
sv_server.launch(log_level="DEBUG")

For more comprehensive examples, check out the examples/ directory:

• examples/a2a-controller.py - A complete A2A-compatible controller implementation

Run any example with:

python examples/a2a-controller.py

Agent API Documentation

The SUPERVAIZER API comes with comprehensive interactive documentation:

• Swagger UI: Available at /docs - Interactive API documentation with request builder and testing tools
• ReDoc: Available at /redoc - Responsive, searchable API reference documentation

These documentation endpoints provide a complete reference of all available API endpoints, request/response formats, and testing capabilities.

Documentation

• API Reference - Complete documentation of classes and methods
• Contributing Guide - How to set up your development environment and contribute

License

This project is licensed under the Mozilla Public License 2.0 License.