{"id":39432843,"url":"https://github.com/supervaize/supervaizer","last_synced_at":"2026-05-04T00:02:19.564Z","repository":{"id":289061008,"uuid":"969996914","full_name":"supervaize/supervaizer","owner":"supervaize","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.","archived":false,"fork":false,"pushed_at":"2026-01-17T14:25:41.000Z","size":1074,"stargazers_count":14,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-18T00:10:02.852Z","etag":null,"topics":["a2a","acp","agentic","agentic-workflow","ai-agents","crewai","langchain","multi-agent","n8n"],"latest_commit_sha":null,"homepage":"https://supervaize.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/supervaize.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"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}},"created_at":"2025-04-21T09:34:05.000Z","updated_at":"2026-01-17T14:21:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"21fcdc55-f84d-4df1-a914-4c4045b2e95b","html_url":"https://github.com/supervaize/supervaizer","commit_stats":null,"previous_names":["supervaize/supervaizer-controller","supervaize/supervaizer"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/supervaize/supervaizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supervaize%2Fsupervaizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supervaize%2Fsupervaizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supervaize%2Fsupervaizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supervaize%2Fsupervaizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supervaize","download_url":"https://codeload.github.com/supervaize/supervaizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supervaize%2Fsupervaizer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28529455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"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","acp","agentic","agentic-workflow","ai-agents","crewai","langchain","multi-agent","n8n"],"created_at":"2026-01-18T04:07:18.863Z","updated_at":"2026-05-04T00:02:19.557Z","avatar_url":"https://github.com/supervaize.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SUPERVAIZER\n\n[Operate AI Agents with confidence]\n\nA Python toolkit for building, managing, and connecting AI agents with full [Agent-to-Agent (A2A)](https://a2a-protocol.org/) protocol support.\n\n[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/downloads/)\n[![A2A Protocol](https://img.shields.io/badge/A2A-Protocol-orange.svg)](https://a2a-protocol.org/)\n[![Test Coverage](https://img.shields.io/badge/Coverage-81%25-brightgreen.svg)](https://github.com/supervaize/supervaizer)\n\n\u003e **⚠️ Beta Disclaimer**: SUPERVAIZER is currently in beta mode. Not everything works as expected yet. Please report any issues you encounter.\n\n- [SUPERVAIZER](#supervaizer)\n  - [Description](#description)\n  - [Quick Start](#quick-start)\n    - [What we'll do](#what-well-do)\n    - [1. Install Supervaizer](#1-install-supervaizer)\n    - [3. Scaffold the controller](#3-scaffold-the-controller)\n    - [(Optional) 4. Configure your Supervaize account \\\u0026 environment](#optional-4-configure-your-supervaize-account--environment)\n    - [5. Start the server 🚀](#5-start-the-server-)\n    - [6. Local mode](#6-local-mode)\n    - [7. Optional parameters](#7-optional-parameters)\n    - [What's next?](#whats-next)\n  - [Features](#features)\n  - [Protocol Support](#protocol-support)\n  - [Cloud Deployment](#cloud-deployment)\n    - [Quick Start](#quick-start-1)\n    - [Deployment Commands](#deployment-commands)\n    - [Features](#features-1)\n    - [Documentation](#documentation)\n  - [Using the CLI](#using-the-cli)\n  - [API Documentation \\\u0026 User Interfaces](#api-documentation--user-interfaces)\n    - [Admin Interface (`/admin`)](#admin-interface-admin)\n      - [Quick Start](#quick-start-2)\n- [Calculating costs](#calculating-costs)\n  - [Documentation](#documentation-1)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n## Description\n\nSUPERVAIZER is a toolkit built for the age of AI interoperability. At its core, it implements the Agent-to-Agent (A2A) protocol, enabling seamless discovery and interaction between agents across different systems and platforms.\n\nWith comprehensive support for the A2A protocol specification, SUPERVAIZER allows you to:\n\n- Enhance the capabilities of your agents, making them automatically discoverable by other A2A compatible systems\n- Expose standardized agent capabilities through agent cards\n- Monitor agent health and status through dedicated endpoints\n- Connect your agents to the growing ecosystem of A2A-compatible tools\n\nBeyond 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.\n\nSUPERVAIZER is the recommended controller to integrate AI Agents into the [supervaize](https://supervaize.com) plateform.\n\n## Quick Start\n\nKickstart a **Python** agent with the **Supervaizer Controller** so it's discoverable and operable by Supervaize.\n\nSee full our full [documentation](https://doc.supervaize.com/docs/category/supervaizer-controller)\n\n### What we'll do\n\n1. **Install Supervaizer** in that project\n2. **Scaffold the controller** and map it to your agent\n3. **Configure secrets \u0026 env**, then **start** the server 🚀\n\n### 1. Install Supervaizer\n\nFirst, navigate to your existing Python AI agent project. This could be built with any framework - LangChain, CrewAI, AutoGen, or your own custom implementation. Supervaizer works as a wrapper around your existing agent, regardless of the underlying framework you're using.\n\n```bash\npip install supervaizer\n```\n\n### 3. Scaffold the controller\n\nGenerate a starter controller in your project:\n\n```bash\nsupervaizer scaffold\n# Success: Created an example file at supervaizer_control_example.py\n```\n\nThis creates **`supervaizer_control_example.py`**. You'll customize it to:\n\n- Define **agent parameters** (secrets, env, required inputs)\n- Define **agent methods** (start/stop/status, etc.)\n- Map those methods to **your agent's functions**\n\n### (Optional) 4. Configure your Supervaize account \u0026 environment\n\nCreate your developer account on the [Supervaize platform](https://www.supervaize.com).\n\nCreate your API Key and collect your environment variables:\n\n```bash\nexport SUPERVAIZE_API_KEY=...\nexport SUPERVAIZE_WORKSPACE_ID=team_1\nexport SUPERVAIZE_API_URL=https://app.supervaize.com\n```\n\n### 5. Start the server 🚀\n\n```bash\n# with the virtual environment active\nsupervaizer start\n```\n\nOr run directly:\n\n```bash\npython supervaizer_control.py\n```\n\nOnce the server is running, you'll have:\n\n- **API docs**: `http://127.0.0.1:8000/docs` (Swagger) and `/redoc`\n- **A2A discovery**: `/.well-known/agents.json`\n- **ACP discovery**: `/agents`\n\n### 6. Local mode\n\nRun the server locally without connecting to Studio:\n\n```bash\nsupervaizer start --local\n```\n\nThis starts the server with your agents from `supervaizer_control.py` alongside a built-in Hello World agent. If no `supervaizer_control.py` exists, only the Hello World agent is loaded.\n\n- **No Studio registration** — the server runs fully offline\n- **`SUPERVAIZER_LOCAL_MODE=true`** is set automatically\n- **API key** defaults to `local-dev` (override with `SUPERVAIZER_API_KEY`)\n- **Disable Hello World** by setting `SUPERVAIZER_DISABLE_HELLO_WORLD=true`\n\n### 7. Optional parameters\n\nConfigure retry behavior for HTTP requests to the Supervaize API:\n\n- **`SUPERVAIZE_HTTP_MAX_RETRIES`**: Number of retry attempts for failed HTTP requests (default: `2`). The client will automatically retry requests that fail with status codes 429, 500, 502, 503, or 504.\n\n```bash\nexport SUPERVAIZE_MAX_HTTP_RETRIES=3  # Will attempt up to 4 times total (1 original + 3 retries)\n```\n\n### What's next?\n\n- Add more **custom methods** (`chat`, `custom`) to extend control\n- Turn on **A2A** discovery for interoperability\n- Hook your controller into Supervaize to **monitor, audit, and operate** the agent\n\nFor detailed instructions on customizing your controller, see the [Controller Setup Guide](https://doc.supervaize.com/docs/supervaizer-controller/controller-setup)\n\n## Features\n\n- **Agent Management**: Register, update, and control agents\n- **Job Control**: Create, track, and manage jobs\n- **Event Handling**: Process and respond to system events\n- **Custom Routes**: Agents can mount their own FastAPI routers under `/api/agents/{slug}/...` for tool endpoints, webhooks, or custom APIs\n- **Scheduled Steps**: Defer step execution to a future time with automatic background polling and workbench controls (execute now, cancel, reschedule)\n- **Human-in-the-Loop (HITL)**: Form-based and dialog-based interactive content review with chat interface\n- **Agent Workbench**: Built-in testing interface with real-time monitoring, job control, HITL forms, and live console\n- **🚀 Cloud Deployment**: Automated deployment to GCP Cloud Run, AWS App Runner, and DigitalOcean App Platform\n- **A2A Protocol Support**: Full integration with the Agent-to-Agent protocol for standardized agent discovery and interaction\n- **Server Communication**: Interact with SUPERVAIZE servers (see [supervaize.com](https://www.supervaize.com) for more info)\n- **Web Admin Interface**: Easy to use web-based admin dashboard for managing jobs, cases, and system monitoring\n\n## Protocol Support\n\nSUPERVAIZER provides comprehensive support for the A2A agent communication protocol. See [Protocol Documentation](docs/PROTOCOLS.md) for complete details.\n\n## Cloud Deployment\n\nSUPERVAIZER includes a powerful deployment CLI that automates the entire process of deploying your agents to production cloud platforms.\n\n### Quick Start\n\n```bash\n# Install with deployment dependencies\npip install supervaizer[deploy]\n\n# Test locally with Docker\nsupervaizer deploy local --generate-api-key --generate-rsa\n\n# Deploy to Google Cloud Run\nsupervaizer deploy up --platform cloud-run --region us-central1\n\n# Deploy to AWS App Runner\nsupervaizer deploy up --platform aws-app-runner --region us-east-1\n\n# Deploy to DigitalOcean App Platform\nsupervaizer deploy up --platform do-app-platform --region nyc\n```\n\n### Deployment Commands\n\n- **`supervaizer deploy plan`** - Preview deployment actions before applying\n- **`supervaizer deploy up`** - Deploy to cloud platform with automated build, push, and verification\n- **`supervaizer deploy down`** - Tear down deployment and clean up resources\n- **`supervaizer deploy status`** - Check deployment status and health\n- **`supervaizer deploy local`** - Local Docker testing with docker-compose\n- **`supervaizer deploy clean`** - Clean up deployment artifacts and state\n\n### Features\n\n- ✅ **Automated Docker Workflow**: Build → Push → Deploy → Verify\n- ✅ **Secret Management**: Secure handling of API keys and RSA keys\n- ✅ **Health Verification**: Automatic health checks at `/.well-known/health`\n- ✅ **Idempotent Deployments**: Safe create/update operations with rollback on failure\n- ✅ **Local Testing**: Full Docker Compose environment for pre-deployment testing\n\n### Documentation\n\n- [RFC-001: Cloud Deployment CLI](docs/rfc/001-cloud-deployment-cli.md) - Complete specification\n- [Local Testing Guide](docs/LOCAL_TESTING.md) - Docker testing documentation\n\n## Using the CLI\n\nSUPERVAIZER includes a command-line interface to simplify setup and operation. See [CLI Documentation](docs/CLI.md) for complete details.\n\nAlso, check the list of [Environment variables](CLI.md#environment-variables).\n\n## API Documentation \u0026 User Interfaces\n\nSUPERVAIZER provides multiple ways to interact with and explore the API. See [REST API Documentation](docs/REST_API.md) for complete details.\n\n### Admin Interface (`/admin`)\n\nA comprehensive web-based admin interface for managing your SUPERVAIZER instance\nSee [Admin documentation](docs/ADMIN_README.md)\n\n#### Quick Start\n\n```python\nfrom supervaizer import Server, Agent\n\n# Create server with admin interface\nserver = Server(\n    agents=[your_agents],\n    api_key=\"your-secure-api-key\",  # Required for admin interface\n    admin_interface=True,  # Enable admin interface (default: True)\n)\n\nserver.launch()\nprint(f\"Admin Interface: http://localhost:8000/admin/\")\n```\n\n# Calculating costs\n\nDevelopers are free to define the cost of the transaction the way they want when updating the cases.\nHere is a way to easily get an estimate of the cost of an LLM transaction (note that litellm also supports custom pricing. )\n\n```python\nfrom litellm import completion_cost\nprompt = \"Explain how transformers work.\"\noutput = \"Transformers use attention mechanisms...\"\nmodel = \"gpt-4\"\ncost = completion_cost(model=model, prompt=prompt, completion=output)\nprint(cost)\n```\n\nA list of costs is maintained here:\n`https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json`\n\n## Documentation\n\nFor a full tutorial and example usage, go to [doc.supervaize.com](https://doc.supervaize.com)\n\n## Contributing\n\nWe welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing feedback, your contributions help make SUPERVAIZER better for everyone.\n\nPlease see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started, coding standards, and the contribution process.\n\n## License\n\nThis project is licensed under the [Mozilla Public License 2.0](LICENSE.md) License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupervaize%2Fsupervaizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupervaize%2Fsupervaizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupervaize%2Fsupervaizer/lists"}