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​

Clone the Hello World example (a minimal Supervaizer agent)

Setup the environment and install dependencies

Configure secrets & env, then start the server 🚀

Clone the Hello World Example​

info

The Supervaizer Controller currently supports Python-based agents.

We'll use the Supervaize Hello World example — a minimal agent that demonstrates all core Supervaizer concepts: GitHub Repository

Clone the repo
git clone https://github.com/supervaize/supervaize_hello_world.git
cd supervaize_hello_world

Setup the Environment​

tip

We recommend using uv for faster dependency management

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 dependencies​

Install dependencies using uv
uv venv
source .venv/bin/activate
uv pip install -e .

Understanding the Controller​

The Hello World example includes a pre-configured supervaizer_control.py that demonstrates:

  • Agent parameters — secrets and environment variables
  • Agent methods — start, stop, and status handlers
  • Server configuration — A2A protocol support and admin interface
Hello World controller supervaizer_control.py
loading...

Creating Your Own Controller​

To scaffold a new controller for your own agent:

Create template controller file
supervaizer scaffold
# Success: Created an example file at supervaizer_control_example.py

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
INFO     | supervaizer.storage:__init__ - [StorageManager] 🗃️ Local DB initialized
INFO     | supervaizer.server:__init__ - [Server launch] 🚀 Deploy Supervaizer routes
INFO     | supervaizer.server:__init__ - [Server launch] 📢 Deploy A2A routes
INFO     | supervaizer.server:__init__ - [Server launch] 💼 Deploy Admin interface @ http://0.0.0.0:8000/admin
INFO     | supervaizer.server:__init__ - [Server launch] API Key authentication enabled
WARNING  | supervaizer.server:__init__ - [Server launch] Using auto-generated API key: xxxxxxxxxxxxxxxxxxxxxxxxxxxx
INFO     | [Server launch] Starting Supervaize Controller API
SUCCESS  | ✅ POST Event SERVER_REGISTER sent
INFO     | [Server launch] Updated agent Hello World Agent
INFO:     Started server process
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (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
  • Admin interface: http://127.0.0.1:8000/admin

What's next?​

  • Deploy to the cloud using the Cloud Deployment Guide for production-ready hosting
  • Add more custom methods (chat, custom) to extend control
  • Enable A2A discovery for agent 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
  • Protocol Support: See the Protocols documentation for A2A protocol details
  • 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.