Model Reference Core

Version: 0.9.8

`account.Account`

Inherits from: account.AccountAbstract

No additional fields beyond parent class.

`account.AccountAbstract`

Inherits from: common.SvBaseModel

Account model for the Supervaize Control API.

This represents an account that can be used to authenticate and communicate with the Supervaize SaaS API. Account parameters are provided by Supervaize.com. Create an account at https://supervaize.com/

The account ID is generated by Supervaize.com. The account API key is provided by Supervaize.com and is used to authenticate requests to the Supervaize Control API. The API URL is provided by Supervaize.com and is the URL of the Supervaize SaaS API.

The account provides methods for registering servers and agents, sending events, and communicating with the Supervaize platform.

Attributes: workspace_id (str): The workspace ID provided by Supervaize.com api_key (str): The API key provided by Supervaize.com for authentication api_url (str): The URL of the Supervaize SaaS API provided by Supervaize.com

Model Fields

Field	Type	Default	Description
`workspace_id`	`str`	required	The workspace ID provided by Supervaize.com
`api_key`	`str`	required	The API key provided by Supervaize.com for authentication
`api_url`	`str`	required	The URL of the Supervaize SaaS API provided by Supervaize.com

Example

{
  "workspace_id": "ws_1234567890abcdef",
  "api_key": "sk_1234567890abcdef",
  "api_url": "https://api.supervaize.com"
}

`agent.Agent`

Inherits from: agent.AgentAbstract

No additional fields beyond parent class.

`agent.AgentAbstract`

Inherits from: common.SvBaseModel

Agent model for the Supervaize Control API.

This represents an agent that can be registered with the Supervaize Control API. It contains metadata about the agent like name, version, description etc. as well as the methods it supports and any parameter configurations.

The agent ID is automatically generated from the name and must match.

Example:

Agent(
name="Email AI Agent",
author="@parthshr370",  # Author of the agent
developer="@alain_sv",  # Developer of the controller
maintainer="@aintainer",
editor="AI Editor",
version="1.0.0",
description="AI-powered email processing agent that can fetch, analyze, generate responses, and send/draft emails",
tags=["email", "ai", "automation", "communication"],
methods=AgentMethods(
job_start=process_email_method, # Job start method
job_stop=job_stop, # Job stop method
job_status=job_status, # Job status method
chat=None,
custom=None,
),
parameters_setup=ParametersSetup.from_list([
Parameter(
    name="IMAP_USERNAME",
    description="IMAP username for email access",
    is_environment=True,
    is_secret=False,
),
Parameter(
    name="IMAP_PASSWORD",
    description="IMAP password for email access",
    is_environment=True,
    is_secret=True,
),
]),
)

Model Fields

Field	Type	Default	Description
`name`	`str`	required	Display name of the agent
`id`	`str`	required	Unique ID generated from name
`author`	`str`	`None`	Author of the agent
`developer`	`str`	`None`	Developer of the controller integration
`maintainer`	`str`	`None`	Maintainer of the integration
`editor`	`str`	`None`	Editor (usually a company)
`version`	`str`	''	Version string
`description`	`str`	''	Description of what the agent does
`tags`	`list[str]`	`None`	Tags for categorizing the agent
`methods`	`AgentMethods`	`None`	Methods supported by this agent
`parameters_setup`	`ParametersSetup`	`None`	Parameter configuration
`server_agent_id`	`str`	`None`	ID assigned by server - Do not set this manually
`server_agent_status`	`str`	`None`	Current status on server - Do not set this manually
`server_agent_onboarding_status`	`str`	`None`	Onboarding status - Do not set this manually
`server_encrypted_parameters`	`str`	`None`	Encrypted parameters from server - Do not set this manually
`max_execution_time`	`int`	3600	Maximum execution time in seconds, defaults to 1 hour

`agent.AgentMethod`

Inherits from: agent.AgentMethodAbstract

No additional fields beyond parent class.

`agent.AgentMethodAbstract`

Represents a method that can be called on an agent.

Attributes: name: Display name of the method method: Name of the actual method in the project's codebase that will be called with the provided parameters params: see below fields: see below description: Optional description of what the method does

params : Dictionary format A simple key-value dictionary of parameters what will be passed to the AgentMethod.method as kwargs. Example:

{
  "verbose": true,
  "timeout": 60,
  "max_retries": 3
}

fields : Form fields format These are the values that will be requested from the user in the Supervaize UI and also passed as kwargs to the AgentMethod.method. A list of field specifications for generating forms/UI, following the django.forms.fields definition see : https://docs.djangoproject.com/en/5.1/ref/forms/fields/ Each field is a dictionary with properties like:
- name: Field identifier
- type: Python type of the field for pydantic validation - note , ChoiceField and MultipleChoiceField are a list[str]
- field_type: Field type (one of: CharField, IntegerField, BooleanField, ChoiceField, MultipleChoiceField)
- choices: For choice fields, list of [value, label] pairs
- default: (optional) Default value for the field
- widget: UI widget to use (e.g. RadioSelect, TextInput)
- required: Whether field is required

Field	Type	Default	Description
`name`	`str`	required	The name of the method
`method`	`str`	required	The name of the method in the project's codebase that will be called with the provided parameters
`params`	`typing.Dict[str, typing.Any]`	`None`	A simple key-value dictionary of parameters what will be passed to the AgentMethod.method as kwargs
`fields`	`typing.List[supervaizer.agent.AgentMethodField]`	`None`	A list of field specifications for generating forms/UI, following the django.forms.fields definition
`description`	`str`	`None`	Optional description of what the method does
`is_async`	`bool`	False	Whether the method is asynchronous

Example

{
  "name": "start",
  "method": "example_agent.example_synchronous_job_start",
  "params": {
    "action": "start"
  },
  "fields": [
    {
      "name": "Company to research",
      "type": "str",
      "field_type": "CharField",
      "max_length": 100,
      "required": true
    }
  ],
  "description": "Start the collection of new competitor summary"
}

`agent.AgentMethodField`

Represents a field specification for generating forms/UI in the Supervaize platform.

Fields are used to define user input parameters that will be collected through the UI and passed as kwargs to the AgentMethod.method. They follow Django forms field definitions for consistency.

Django Widgets

** field_type - available field types ** Django Field classes

CharField - Text input
IntegerField - Number input
BooleanField - Checkbox
ChoiceField - Dropdown with options
MultipleChoiceField - Multi-select
JSONField - JSON data input

Field	Type	Default	Description
`name`	`str`	required	The name of the field - displayed in the UI
`type`	`Any`	required	Python type of the field for pydantic validation - note , ChoiceField and MultipleChoiceField are a list[str]
`field_type`	`<enum 'FieldTypeEnum'>`	`CharField`	Field type for persistence
`description`	`str`	`None`	Description of the field - displayed in the UI
`choices`	`list[tuple[str, str]]` \| `list[str]`	`None`	For choice fields, list of [value, label] pairs
`default`	`Any`	`None`	Default value for the field - displayed in the UI
`widget`	`str`	`None`	UI widget to use (e.g. RadioSelect, TextInput) - as a django widget name
`required`	`bool`	False	Whether field is required for form submission

Examples

Example 1:

{
  "name": "color",
  "type": "list[str]",
  "field_type": "MultipleChoiceField",
  "choices": [
    [
      "B",
      "Blue"
    ],
    [
      "R",
      "Red"
    ],
    [
      "G",
      "Green"
    ]
  ],
  "widget": "RadioSelect",
  "required": true
}

Example 2:

{
  "name": "age",
  "type": "int",
  "field_type": "IntegerField",
  "widget": "NumberInput",
  "required": false
}

`parameter.ParametersSetup`

Inherits from: common.SvBaseModel

ParametersSetup model for the Supervaize Control API.

This represents a collection of parameters that can be used by an agent. It contains a dictionary of parameters, where the key is the parameter name and the value is the parameter object.

Example:

ParametersSetup.from_list([
    Parameter(name="parameter1", value="value1"),
    Parameter(name="parameter2", value="value2", description="desc2"),
])

Model Fields

Field	Type	Default	Description
`definitions`	`Dict[str, parameter.Parameter]`	required	A dictionary of Parameters, where the key is the parameter name and the value is the parameter object.

`parameter.Parameter`

Inherits from: parameter.ParameterAbstract

No additional fields beyond parent class.

`parameter.ParameterAbstract`

Inherits from: common.SvBaseModel

Base model for agent parameters that defines configuration and metadata.

Parameters can be environment variables, secrets, or regular configuration values that are used by agents during execution. The Supervaize platform uses this model to manage parameter definitions and values.

Model Fields

Field	Type	Default	Description
`name`	`str`	required	The name of the parameter, as used in the agent code
`description`	`str`	`None`	The description of the parameter, used in the Supervaize UI
`is_environment`	`bool`	False	Whether the parameter is set as an environment variable
`value`	`str`	`None`	The value of the parameter - provided by the Supervaize platform
`is_secret`	`bool`	False	Whether the parameter is a secret - hidden from the user in the Supervaize UI
`is_required`	`bool`	False	Whether the parameter is required, used in the Supervaize UI

Example

{
  "name": "OPEN_API_KEY",
  "description": "OpenAPI Key",
  "is_environment": true,
  "is_secret": true,
  "is_required": true
}

`server.Server`

Inherits from: server.ServerAbstract

No additional fields beyond parent class.

`server.ServerAbstract`

Inherits from: common.SvBaseModel

API Server for the Supervaize Controller.

The server is a FastAPI application (see https://fastapi.tiangolo.com/ for details and advanced parameters)

This represents the main server instance that manages agents and provides the API endpoints for the Supervaize Control API. It handles agent registration, job execution, and communication with the Supervaize platform.

The server can be configured with various endpoints (A2A, ACP, admin interface) and supports encryption/decryption of parameters using RSA keys.

Note that when the supervisor ccount is set, the A2A protocol is automatically activated to provide HEALTH CHECK endpoints.

public_url: full url (including scheme and port) to use for outbound connections and registration. This is especially important in Docker environments where the binding address (0.0.0.0) can't be used for outbound connections. Set to 'host.docker.internal' for Docker or the appropriate service name in container environments. Examples:

In Docker, set to 'http://host.docker.internal' to reach the host machine
In Kubernetes, might be set to the service name or external DNS If not provided, falls back to using the listening host.

Model Fields

Field	Type	Default	Description
`scheme`	`str`	required	URL scheme (http or https)
`host`	`str`	required	Host to bind the server to (e.g., 0.0.0.0 for all interfaces)
`port`	`int`	required	Port to bind the server to
`environment`	`str`	required	Environment name (e.g., dev, staging, prod)
`mac_addr`	`str`	required	MAC address to use for server identification
`debug`	`bool`	required	Whether to enable debug mode
`agents`	`List[agent.Agent]`	required	List of agents to register with the server
`app`	`FastAPI`	required	FastAPI application instance
`reload`	`bool`	required	Whether to enable auto-reload
`supervisor_account`	`Account`	`None`	Account of the supervisor - can be created at supervaize.com
`a2a_endpoints`	`bool`	True	Whether to enable A2A endpoints
`acp_endpoints`	`bool`	True	Whether to enable ACP endpoints
`private_key`	`RSAPrivateKey`	required	RSA private key for secret parameters encryption - Used in server-to-agent communication - Not needed by user
`public_key`	`RSAPublicKey`	required	RSA public key for secret parameters encryption - Used in agent-to-server communication - Not needed by user
`public_url`	`str`	`None`	Public including scheme and port to use for inbound connections
`api_key`	`str`	`None`	Force the API key to access the supervaizer endpoints - if not provided, a random key will be generated
`api_key_header`	`APIKeyHeader`	`None`	API key header for authentication

Examples

Example 1:

{
  "agents": "[agent]",
  "a2a_enabled": true,
  "supervisor_account": null
}

Example 2:

{
  "scheme": "http",
  "host": "0.0.0.0",
  "port": 8000,
  "environment": "dev",
  "mac_addr": "00-11-22-33-44-55",
  "debug": false,
  "reload": false,
  "a2a_endpoints": true,
  "acp_endpoints": true
}

Uploaded on 2025-08-12 14:19:38

account.Account​

account.AccountAbstract​

Model Fields​

Example​

agent.Agent​

agent.AgentAbstract​

Model Fields​

agent.AgentMethod​

agent.AgentMethodAbstract​

Example​

agent.AgentMethodField​

Examples​

parameter.ParametersSetup​

Model Fields​

parameter.Parameter​

parameter.ParameterAbstract​

Model Fields​

Example​

server.Server​

server.ServerAbstract​

Model Fields​

Examples​

`account.Account`

`account.AccountAbstract`

Model Fields

Example

`agent.Agent`

`agent.AgentAbstract`

Model Fields

`agent.AgentMethod`

`agent.AgentMethodAbstract`

Example

`agent.AgentMethodField`

Examples

`parameter.ParametersSetup`

Model Fields

`parameter.Parameter`

`parameter.ParameterAbstract`

Model Fields

Example

`server.Server`

`server.ServerAbstract`

Model Fields

Examples