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/runwaize/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=your-workspace-slug
export SUPERVAIZE_API_URL=https://app.supervaize.com

SUPERVAIZE_WORKSPACE_ID must be the exact Studio workspace slug. The Studio user who owns the API key must belong to this workspace and retain Developer access.

Workspace authorization for Studio-managed v2 agents​

When your controller registers with Studio and A2A is enabled, set the workspace authorization variables in addition to the API credentials above. In Studio, open Developer → Environment variables and copy the generated values for your workspace:

export SUPERVAIZER_WORKSPACE_AUTH_REQUIRED=true
export SUPERVAIZER_WORKSPACE_AUTH_ISSUER=https://studio.supervaize.com
export SUPERVAIZER_WORKSPACE_AUTH_JWKS_URL=https://app.supervaize.com/w/your-workspace-slug/api/v1/workspace-agent-grants/jwks/

The issuer is the Studio web origin used to sign authorization tokens. The JWKS URL uses the Django API origin and /w/<workspace-slug>/api/v1/... route; it is public and provides the verification key. Copy the generated values from Studio when available. This is separate from SUPERVAIZE_API_KEY (agent → Studio) and SUPERVAIZER_API_KEY (Studio → controller). If using a different Studio deployment, use that deployment's generated values instead of these production examples.

For local development only​

:::warning 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)

:::tip 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.