Agent Tables

agent_mappings

Maps Ultravox agents to local records with configuration overrides. Each mapping belongs to an agency and can optionally be linked to a client and campaign.

Column	Type	Default	Nullable	Description
id	uuid	uuid_generate_v4()	no	Primary key
agency_id	uuid	—	no	FK → agencies.id
ultravox_agent_id	varchar(255)	—	no	Ultravox-side agent identifier
ultravox_agent_name	varchar(255)	—	yes	Agent display name
client_id	uuid	—	yes	FK → clients.id (optional assignment)
campaign_id	uuid	—	yes	FK → campaigns.id (optional assignment)
default_direction	call_direction	—	yes	Default call direction for this agent
system_prompt	text	—	yes	The agent's system prompt
voice	varchar(100)	—	yes	Voice ID from Ultravox
language_hint	varchar(10)	'en'	no	Language hint for speech recognition
temperature	numeric(3,2)	0.4	no	LLM temperature (0.00–1.00)
first_speaker_text	text	—	yes	Text the agent speaks when answering
recording_enabled	boolean	true	no	Whether calls are recorded
max_duration_seconds	integer	3600	no	Maximum call duration (1–86400)
tools	jsonb	'[]'	no	Tool IDs assigned to this agent
last_synced_at	timestamptz	—	yes	Last successful sync with Ultravox
sync_error	text	—	yes	Last sync error message
managed_by_virsyn	boolean	false	no	Whether Virsyn manages this agent
created_at	timestamptz	now()	no	Record creation timestamp
updated_at	timestamptz	now()	no	Last update timestamp (auto-updated)

Constraints:

Constraint	Type	Details
agent_mappings_pkey	Primary key	id
agent_mappings_unique_per_agency	Unique	(agency_id, ultravox_agent_id)
agent_mappings_agency_id_fkey	Foreign key	agency_id → agencies(id) ON DELETE CASCADE
agent_mappings_client_id_fkey	Foreign key	client_id → clients(id) ON DELETE SET NULL
agent_mappings_campaign_id_fkey	Foreign key	campaign_id → campaigns(id) ON DELETE SET NULL
agent_mappings_temperature_range	Check	temperature >= 0.0 AND temperature <= 1.0
agent_mappings_max_duration_positive	Check	max_duration_seconds > 0 AND max_duration_seconds <= 86400

Indexes:

Index	Columns
idx_agent_mappings_agency_id	agency_id
idx_agent_mappings_ultravox_agent	ultravox_agent_id
idx_agent_mappings_client_id	client_id
idx_agent_mappings_campaign_id	campaign_id

Triggers:

Trigger	Event	Function
update_agent_mappings_updated_at	BEFORE UPDATE	update_updated_at_column()

Related edge functions: agents-create, agents-list, agents-get, agents-update, agents-delete, agents-assign, agents-sync, save-agent-mapping

---

agency_tools

Tools available to agents during calls. Synced from Ultravox and cached locally.

Column	Type	Default	Nullable	Description
id	uuid	uuid_generate_v4()	no	Primary key
agency_id	uuid	—	no	FK → agencies.id
ultravox_tool_id	text	—	no	Ultravox-side tool identifier
name	text	—	no	Tool display name
description	text	—	yes	Human-readable tool description
tool_type	text	—	yes	Tool classification (e.g., http, client)
ownership	text	—	yes	Who owns the tool (user, system)
created_at_ultravox	timestamptz	—	yes	When created in Ultravox
definition	jsonb	'{}'	no	Full tool definition from Ultravox
http_base_url	text	—	yes	Base URL for HTTP-type tools
http_method	text	—	yes	HTTP method for HTTP-type tools
dynamic_parameters	jsonb	'[]'	yes	Parameters resolved at runtime
static_parameters	jsonb	'[]'	yes	Fixed parameters
category	varchar(50)	—	yes	UI grouping category
tags	text[]	'{}'	yes	Searchable tags
icon	varchar(50)	—	yes	UI icon identifier
is_active	boolean	true	no	Whether the tool is enabled
managed_by_virsyn	boolean	false	no	Whether Virsyn manages this tool
last_synced_at	timestamptz	—	yes	Last successful sync
sync_error	text	—	yes	Last sync error message
created_at	timestamptz	now()	no	Record creation timestamp
updated_at	timestamptz	now()	no	Last update timestamp (auto-updated)
created_by	uuid	—	yes	FK → users.id

Constraints:

Constraint	Type	Details
agency_tools_pkey	Primary key	id
agency_tools_unique_ultravox_id	Unique	(agency_id, ultravox_tool_id)
agency_tools_agency_id_fkey	Foreign key	agency_id → agencies(id) ON DELETE CASCADE
agency_tools_created_by_fkey	Foreign key	created_by → users(id) ON DELETE SET NULL
agency_tools_name_not_empty	Check	length(trim(name)) > 0

Indexes:

Index	Columns	Notes
idx_agency_tools_agency_id	agency_id	Agency-scoped queries
idx_agency_tools_ultravox_id	ultravox_tool_id	Lookup by Ultravox ID
idx_agency_tools_tool_type	(agency_id, tool_type)	Filter by type
idx_agency_tools_active	(agency_id, is_active)	Active tools only (WHERE is_active = true)
idx_agency_tools_category	(agency_id, category)	Filter by category (WHERE category IS NOT NULL)

Triggers:

Trigger	Event	Function
update_agency_tools_updated_at	BEFORE UPDATE	update_updated_at_column()

Related edge functions: tools-list, tools-get, tools-sync

---

ultravox_voices

Cached voice catalog from Ultravox. Not agency-scoped — shared across all agencies.

Column	Type	Default	Nullable	Description
id	text	—	no	Primary key — Ultravox voice ID
name	text	—	no	Voice display name
description	text	—	yes	Voice description
language_label	text	—	yes	Human-readable language label
primary_language	text	—	yes	ISO language code
ownership	text	—	yes	Voice ownership (fixie, user)
billing_style	text	—	yes	How the voice is billed
provider	text	—	yes	TTS provider name
preview_url	text	—	yes	URL to a voice sample
definition	jsonb	—	yes	Full voice definition from Ultravox
last_synced_at	timestamptz	now()	no	Last sync timestamp

Constraints:

Constraint	Type	Details
ultravox_voices_pkey	Primary key	id

Indexes:

Index	Columns
idx_ultravox_voices_name	name
idx_ultravox_voices_primary_language	primary_language
idx_ultravox_voices_provider	provider
idx_ultravox_voices_ownership	ownership

Related edge functions: voices-list, voices-sync