Create Agent

Creates a new voice agent in Ultravox with a full call template configuration and stores a corresponding local mapping record in the agent_mappings table. The local mapping links the Ultravox agent to an agency, and optionally to a client, campaign, and default call direction.

Endpoint

Property	Value
Function Name	agents-create
HTTP Method	POST
Authentication	Supabase JWT (Bearer token)
Required Role	agency_owner or agency_admin

Request

Headers

Authorization: Bearer <supabase_jwt_token>
Content-Type: application/json

Body

Field	Type	Required	Description
name	string	Yes	Display name for the agent. Sanitized for Ultravox (alphanumeric, underscores, hyphens; max 64 chars).
system_prompt	string	Yes	The system prompt that defines the agent's behavior.
voice	string	No	Voice identifier for the agent's TTS voice.
language_hint	string	No	Language hint for speech recognition. Defaults to "en".
temperature	number	No	LLM temperature setting. Defaults to 0.4.
first_speaker_text	string	No	Text the agent speaks first when a call begins.
recording_enabled	boolean	No	Whether call recording is enabled. Defaults to true.
max_duration_seconds	number	No	Maximum call duration in seconds. Stored as 3600 in local mapping if not provided.
tools	any[]	No	Array of tool definitions available to the agent during calls.
client_id	string	No	UUID of the client to assign this agent to. Must belong to the caller's agency.
campaign_id	string	No	UUID of the campaign to assign this agent to. Must exist and, if client_id is also provided, must belong to that client.
default_direction	"inbound" | "outbound"	No	Default call direction for this agent.

Response

Success (201)

{
  "ultravox_agent_id": "uv-agent-abc123",
  "mapping_id": "uuid-of-local-mapping",
  "agent": {
    "id": "uv-agent-abc123",
    "name": "My_Agent",
    "system_prompt": "You are a helpful assistant...",
    "model": "fixie-ai/ultravox-70B",
    "voice": "terrence",
    "temperature": 0.4
  }
}

Partial Success (201)

If the agent is created in Ultravox but the local mapping insert fails, a 201 response is still returned with a warning:

{
  "ultravox_agent_id": "uv-agent-abc123",
  "mapping_id": null,
  "agent": {
    "id": "uv-agent-abc123",
    "name": "My_Agent",
    "system_prompt": "You are a helpful assistant...",
    "model": null,
    "voice": null,
    "temperature": 0.4
  },
  "warning": "Agent created in Ultravox but local mapping failed",
  "mapping_error": "error details..."
}

Error Responses

Status	Condition
400	name is missing or empty
400	system_prompt is missing
400	client_id is invalid or does not belong to the caller's agency
400	campaign_id is invalid or does not exist
400	campaign_id does not belong to the specified client_id
400	Ultravox API key is not configured for the agency
401	Missing or invalid authorization header
403	User is not associated with an agency
403	User role is not agency_owner or agency_admin
405	HTTP method is not POST
500	Failed to retrieve API credentials from the database
500	Unexpected server error
502	Ultravox API returned an error when creating the agent

Behavior

• Authenticates the user via Supabase JWT and verifies they belong to an agency with the agency_owner or agency_admin role.
• Retrieves the agency's Ultravox API key by calling the get_agency_credentials RPC function.
• Validates required fields (name, system_prompt) and optional relational fields (client_id, campaign_id).
• Sanitizes the agent name to match the Ultravox naming constraint (^[a-zA-Z0-9_-]{1,64}$): replaces spaces with underscores, strips invalid characters, and truncates to 64 characters.
• Builds an Ultravox agent payload with a callTemplate containing the system prompt, language hint, temperature, recording settings, and optional voice, max duration, first speaker text, and tools.
• Sends a POST request to https://api.ultravox.ai/api/agents to create the agent.
• On success, inserts a record into the agent_mappings table with the Ultravox agent ID, agency ID, full configuration snapshot, and optional client/campaign/direction assignments. Sets managed_by_virsyn to true and records last_synced_at.
• If the local mapping insert fails after a successful Ultravox creation, returns a partial success response with a warning.

Database Tables

Table	Operation	Description
users	Read	Fetches user profile to determine agency_id and role
clients	Read	Validates client_id belongs to the agency (if provided)
campaigns	Read	Validates campaign_id exists and belongs to the correct client (if provided)
agent_mappings	Insert	Stores the local mapping linking the Ultravox agent to the agency

External APIs

API	Method	Endpoint	Description
Ultravox	POST	/api/agents	Creates the agent in Ultravox

Related Functions

• List Agents -- List all agents with merged Ultravox and local data
• Get Agent -- Fetch a single agent with full details
• Update Agent -- Update an existing agent's configuration
• Delete Agent -- Delete an agent from Ultravox and local storage