# SUPERVAIZER
[[Operate AI Agents with confidence]]
A Python toolkit for building, managing, and connecting AI agents with full [Agent-to-Agent (A2A)](https://google.github.io/A2A/#/) and [Agent Communication Protocol (ACP)](https://github.com/i-am-bee/ACP) support.
[](https://www.python.org/downloads/)
[](https://github.com/supervaize/supervaizer)
[](https://google.github.io/A2A/)
[](https://github.com/i-am-bee/ACP)
[](https://github.com/supervaize/supervaizer)
- [SUPERVAIZER](#supervaizer)
- [Description](#description)
- [Quick Start](#quick-start)
- [What we'll do](#what-well-do)
- [1. Install Supervaizer](#1-install-supervaizer)
- [3. Scaffold the controller](#3-scaffold-the-controller)
- [(Optional) 4. Configure your Supervaize account \& environment](#optional-4-configure-your-supervaize-account--environment)
- [5. Start the server 🚀](#5-start-the-server-)
- [What's next?](#whats-next)
- [Features](#features)
- [Protocol Support](#protocol-support)
- [Using the CLI](#using-the-cli)
- [API Documentation \& User Interfaces](#api-documentation--user-interfaces)
- [Admin Interface (`/admin`)](#admin-interface-admin)
- [Quick Start](#quick-start-1)
- [Calculating costs](#calculating-costs)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)
## Description
SUPERVAIZER is a toolkit built for the age of AI interoperability. At its core, it implements Google's Agent-to-Agent (A2A) protocol and IBM's Agent Communication Protocol (ACP), enabling seamless discovery and interaction between agents across different systems and platforms.
With comprehensive support for the A2A/ACP protocols, specification, SUPERVAIZER allows you to:
- Enhance the capabilities of your agents, making them automatically discoverable by other A2A/ACP compatible 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.
## Quick Start
Kickstart a **Python** agent with the **Supervaizer Controller** so it's discoverable and operable by Supervaize.
### What we'll do
1. **Install Supervaizer** in that project
2. **Scaffold the controller** and map it to your agent
3. **Configure secrets & env**, then **start** the server 🚀
### 1. Install Supervaizer
First, 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.
```bash
pip install supervaizer
```
### 3. Scaffold the controller
Generate a starter controller in your project:
```bash
supervaizer scaffold
# Success: Created an example file at supervaizer_control_example.py
```
This creates **`supervaizer_control_example.py`**. You'll customize it to:
- Define **agent parameters** (secrets, env, required inputs)
- Define **agent methods** (start/stop/status, etc.)
- Map those methods to **your agent's functions**
### (Optional) 4. Configure your Supervaize account & environment
Create your developer account on the [Supervaize platform](https://www.supervaize.com).
Create your API Key and collect your environment variables:
```bash
export SUPERVAIZE_API_KEY=...
export SUPERVAIZE_WORKSPACE_ID=team_1
export SUPERVAIZE_API_URL=https://app.supervaize.com
```
### 5. Start the server 🚀
```bash
# with the virtual environment active
supervaizer start
```
Or run directly:
```bash
python supervaizer_control.py
```
Once the server is running, you'll have:
- **API docs**: `http://127.0.0.1:8000/docs` (Swagger) and `/redoc`
- **A2A discovery**: `/.well-known/agents.json`
- **ACP discovery**: `/agents`
### What's next?
- Add more **custom methods** (`chat`, `custom`) to extend control
- Turn on **A2A / ACP** discovery for interoperability
- Hook your controller into Supervaize to **monitor, audit, and operate** the agent
For detailed instructions on customizing your controller, see the [Controller Setup Guide](https://doc.supervaize.com/docs/supervaizer-controller/controller-setup-guide).
## Features
- **Agent Management**: Register, update, and control agents
- **Job Control**: Create, track, and manage jobs
- **Event Handling**: Process and respond to system events
- Protocol support
- **A2A Protocol **: Integration with Google's Agent-to-Agent protocol for interoperability
- **ACP Protocol **: Integration with IBM/BeeAI's Agent Communication Protocol for standardized agent discovery and interaction
- **Server Communication**: Interact with SUPERVAIZE servers (see [supervaize.com](https://www.supervaize.com) for more info)
- **Web Admin Interface**: Easy to use web-based admin dashboard for managing jobs, cases, and system monitoring
## Protocol Support
SUPERVAIZER provides comprehensive support for multiple agent communication protocols. See [Protocol Documentation](docs/PROTOCOLS.md) for complete details.
## Using the CLI
SUPERVAIZER includes a command-line interface to simplify setup and operation. See [CLI Documentation](docs/CLI.md) for complete details.
Also, check the list of [Environment variables](CLI.md#environment-variables).
## API Documentation & User Interfaces
SUPERVAIZER provides multiple ways to interact with and explore the API. See [REST API Documentation](docs/REST_API.md) for complete details.
### Admin Interface (`/admin`)
A comprehensive web-based admin interface for managing your SUPERVAIZER instance
See [Admin documentation](docs/ADMIN_README.md)
#### Quick Start
```python
from supervaizer import Server, Agent
# Create server with admin interface
server = Server(
agents=[your_agents],
api_key="your-secure-api-key", # Required for admin interface
admin_interface=True, # Enable admin interface (default: True)
)
server.launch()
print(f"Admin Interface: http://localhost:8000/admin/")
```
# Calculating costs
Developers are free to define the cost of the transaction the way they want when updating the cases.
Here is a way to easily get an estimate of the cost of an LLM transaction (note that litellm also supports custom pricing. )
```python
from litellm import completion_cost
prompt = "Explain how transformers work."
output = "Transformers use attention mechanisms..."
model = "gpt-4"
cost = completion_cost(model=model, prompt=prompt, completion=output)
print(cost)
```
A list of costs is maintained here:
`https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json`
## Documentation
For a full tutorial and example usage, go to [doc.supervaize.com](https://doc.supervaize.com)
## Contributing
We 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.
Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started, coding standards, and the contribution process.
## License
This project is licensed under the [Mozilla Public License 2.0](LICENSE.md) License.
Raw data
{
"_id": null,
"home_page": null,
"name": "supervaizer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "AI, agent, agentic, controller, supervaize, workflow",
"author": null,
"author_email": "Alain Prasquier - Supervaize <alain@supervaize.com>",
"download_url": "https://files.pythonhosted.org/packages/0e/f1/5b6ccabdd0b30e82a38f0533d2d7145291fad24fc6a335ce29b4a52f18bf/supervaizer-0.9.8.tar.gz",
"platform": null,
"description": "# 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://google.github.io/A2A/#/) and [Agent Communication Protocol (ACP)](https://github.com/i-am-bee/ACP) support.\n\n[](https://www.python.org/downloads/)\n[](https://github.com/supervaize/supervaizer)\n[](https://google.github.io/A2A/)\n[](https://github.com/i-am-bee/ACP)\n[](https://github.com/supervaize/supervaizer)\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 \\& environment](#optional-4-configure-your-supervaize-account--environment)\n - [5. Start the server \ud83d\ude80](#5-start-the-server-)\n - [What's next?](#whats-next)\n - [Features](#features)\n - [Protocol Support](#protocol-support)\n - [Using the CLI](#using-the-cli)\n - [API Documentation \\& User Interfaces](#api-documentation--user-interfaces)\n - [Admin Interface (`/admin`)](#admin-interface-admin)\n - [Quick Start](#quick-start-1)\n- [Calculating costs](#calculating-costs)\n - [Documentation](#documentation)\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 Google's Agent-to-Agent (A2A) protocol and IBM's Agent Communication Protocol (ACP), enabling seamless discovery and interaction between agents across different systems and platforms.\n\nWith comprehensive support for the A2A/ACP protocols, specification, SUPERVAIZER allows you to:\n\n- Enhance the capabilities of your agents, making them automatically discoverable by other A2A/ACP 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\n## Quick Start\n\nKickstart a **Python** agent with the **Supervaizer Controller** so it's discoverable and operable by Supervaize.\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 & env**, then **start** the server \ud83d\ude80\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 & 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 \ud83d\ude80\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### What's next?\n\n- Add more **custom methods** (`chat`, `custom`) to extend control\n- Turn on **A2A / ACP** 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-guide).\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- Protocol support\n - **A2A Protocol **: Integration with Google's Agent-to-Agent protocol for interoperability\n - **ACP Protocol **: Integration with IBM/BeeAI's Agent Communication 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 multiple agent communication protocols. See [Protocol Documentation](docs/PROTOCOLS.md) for complete details.\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 & 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",
"bugtrack_url": null,
"license": null,
"summary": "Controller system for Supervaize",
"version": "0.9.8",
"project_urls": {
"Documentation": "https://doc.supervaize.com",
"Homepage": "https://supervaize.com",
"Repository": "https://github.com/supervaize/supervaizer"
},
"split_keywords": [
"ai",
" agent",
" agentic",
" controller",
" supervaize",
" workflow"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8bedb33607f3e079627cc7edb48df744832ca2ededc4da5bd3f8c36f9a22f184",
"md5": "369253e582af8a51aab808ad652aa512",
"sha256": "631717ecf69e5a928ad57238f5f9133c93666103a11c2b3d0a39311f3a6a360e"
},
"downloads": -1,
"filename": "supervaizer-0.9.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "369253e582af8a51aab808ad652aa512",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 125175,
"upload_time": "2025-08-12T11:27:06",
"upload_time_iso_8601": "2025-08-12T11:27:06.113979Z",
"url": "https://files.pythonhosted.org/packages/8b/ed/b33607f3e079627cc7edb48df744832ca2ededc4da5bd3f8c36f9a22f184/supervaizer-0.9.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0ef15b6ccabdd0b30e82a38f0533d2d7145291fad24fc6a335ce29b4a52f18bf",
"md5": "7fbd2ca68a8e6b62a672eea49cc3d315",
"sha256": "7fd933b5bff0394c01fe708bd0539509e9b4375f4b8248f220fbd407f4636930"
},
"downloads": -1,
"filename": "supervaizer-0.9.8.tar.gz",
"has_sig": false,
"md5_digest": "7fbd2ca68a8e6b62a672eea49cc3d315",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 95514,
"upload_time": "2025-08-12T11:27:07",
"upload_time_iso_8601": "2025-08-12T11:27:07.849219Z",
"url": "https://files.pythonhosted.org/packages/0e/f1/5b6ccabdd0b30e82a38f0533d2d7145291fad24fc6a335ce29b4a52f18bf/supervaizer-0.9.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 11:27:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "supervaize",
"github_project": "supervaizer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "supervaizer"
}
JSON
