Skip to main content

Supervaizer Controller — Quickstart

Kickstart a Python agent with the Supervaizer Controller so it’s discoverable and operable by Supervaize.

What we'll do​

Get an agent (we'll reuse an open source email agent)

Install Supervaizer in that project

Scaffold the controller and map it to your agent

Configure secrets & env, then start the server 🚀

Create or find an AI Agent​

An open source langchain agent​

info

The Supervaizer Controller currently supports Python-based agents.

We’ll use this example agent:
Email AI Agent by parthshr370 — GitHub • Guide

Clone the repo
git clone https://github.com/alain-sv/Email-AI-Agent.git
cd Email-AI-Agent

Setup the agent​

tip

We are using uv as a matter of preference & performance

Install the dependencies with your preferred tool:

Install uv — see https://docs.astral.sh/uv/​

Install UV on Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

Create a virtual environment and install requirements​

Install requirements using uv
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

Install Supervaizer in the agent project​

Install supervaizer using uv
uv pip install supervaizer

Scaffold the controller​

Generate an example​

Generate a starter controller in your project:

Create template controller file
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

Shortcut​

Get the fully customized controller from GitHub Email-AI-Agent Supervaizer fork.

Full example controller supervaizer_control.py
loading...

Step by step​

For detailed instructions on customizing your controller, see the Controller Setup Guide.

Configure your supervaize account & environment​

Supervaize account and credentials​

Create your developer account on the Supervaize platform.

Create your API Key and collect your environment variables.

tip

Use direnv for easy management of environment variables in .envrc file.

Or setup python-dotenv in your python project.

Export Environment variables in for .envrc
export SUPERVAIZE_API_KEY=...
export SUPERVAIZE_WORKSPACE_ID=team_1
export SUPERVAIZE_API_URL=https://app.supervaize.com

For local development only​

Local development

If the agent is not deployed to a publicly accessible server, you need to install a Tunneling solution so that supervaize can operate your agent. Here are the instructions to setup a tunnel for your local development

Store your public hostname in SUPERVAIZER_HOST environment variable.

export SUPERVAIZER_HOST=silly-peaches-chapter.loca.lt

Start the server 🚀​

# with the virtual environment active
supervaizer start
2025-08-10 01:11:50.152 | INFO     | supervaizer.storage:__init__:`3 - [StorageManager] 🗃️ Local DB initialized at /Volumes/SSDext1TB/Documents/GitRepo/SUPERVAIZE/9agents/Email-AI-Agent/data/entities.json
2025-08-10 01:11:50.533 | INFO     | supervaizer.server:__init__:303 - [Server launch] 🚀 Deploy Supervaizer routes
2025-08-10 01:11:50.551 | INFO     | supervaizer.server:__init__:308 - [Server launch] 📢 Deploy A2A routes
2025-08-10 01:11:50.552 | INFO     | supervaizer.server:__init__:311 - [Server launch] 📢 Deploy ACP routes
2025-08-10 01:11:50.554 | INFO     | supervaizer.server:__init__:316 - [Server launch] 💼 Deploy Admin interface @ http://0.0.0.0:8001/admin
2025-08-10 01:11:50.567 | INFO     | supervaizer.server:save_server_info_to_storage:103 - [Server] Server info saved to storage: 0.0.0.0:8001
2025-08-10 01:11:50.567 | INFO     | supervaizer.storage:load_running_entities_on_startup:431 - [Storage] Entity re-loading complete: 0 running jobs, 0 running cases
2025-08-10 01:11:50.567 | INFO     | supervaizer.server:__init__:339 - [Server launch] API Key authentication enabled
2025-08-10 01:11:50.567 | WARNING  | supervaizer.server:__init__:342 - [Server launch] Using auto-generated API key: xxxxxxxxxxxxxxxxxxxxxxxxxxxx
2025-08-10 01:11:50.573| INFO | [Server launch] Starting Supervaize Controller API v0.9.4 - Log : debug
2025-08-10 01:11:51.644| DEBUG | [API Success] ✅ POST Event SERVER_REGISTER sent : 01K28E7S6Y5617Q0QPAPEJHWS2
2025-08-10 01:11:51.644| SUCCESS | ✅ POST Event SERVER_REGISTER sent : 01K28E7S6Y5617Q0QPAPEJHWS2
2025-08-10 01:11:53.084| DEBUG | [API Success] ✅ GET Agent <email-ai-agent>
2025-08-10 01:11:53.084| DEBUG | [Agent not onboarded] skipping encrypted parameters
2025-08-10 01:11:53.084| INFO | [Server launch] Updated agent Email AI Agent
INFO:     Started server process [87009]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)
Verify endpoints

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.

Need Help?​

If you run into issues, check the Troubleshooting Guide for common problems and solutions.

Reference​

  • Parameter Model: docs link
  • A2A example: examples/a2a-controller.py (in the supervaizer package)
  • API docs: visit /docs and /redoc when the server is running
note

Supervaizer is the controller & interoperability layer; it doesn’t replace your agent framework. It makes your agent discoverable, operable, and governable.