Agents

Agents are the core entity in VOCALS. Each agent defines a conversational AI persona with its own STT, LLM, and TTS provider configuration, system prompt, voice settings, and phone number assignments.

List Agents

GET /agents

Returns all agents for the current tenant, ordered by name.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Support Agent",
    "active_stt_provider_id": "...",
    "active_llm_provider_id": "...",
    "active_tts_provider_id": "...",
    "is_active": true,
    "phone_count": 2,
    "has_webhook": true,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-20T14:00:00Z"
  }
]

Response Fields (List)

Field	Type	Description
id	uuid	Agent ID
name	string	Agent display name
active_stt_provider_id	uuid | null	Assigned STT provider
active_llm_provider_id	uuid | null	Assigned LLM provider
active_tts_provider_id	uuid | null	Assigned TTS provider
is_active	boolean	Whether the agent is active
phone_count	integer	Number of assigned phone numbers
has_webhook	boolean	Whether a webhook URL is configured
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Get Agent

GET /agents/{agent_id}

Returns full agent detail including phone number assignments.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Support Agent",
  "active_stt_provider_id": "...",
  "active_llm_provider_id": "...",
  "active_tts_provider_id": "...",
  "system_prompt": "You are a helpful support agent...",
  "welcome_message": "Hello! How can I help you today?",
  "voice_id": "rachel",
  "language": "en",
  "silence_threshold": 0.5,
  "max_call_duration": 300,
  "barge_in_sensitivity": "medium",
  "interruptible": true,
  "welcome_interruptible": false,
  "amd_enabled": false,
  "tts_config": { "speed": 1.0 },
  "webhook_url": "https://example.com/webhook",
  "webhook_secret": "whsec_...",
  "is_active": true,
  "phone_numbers": [
    {
      "id": "...",
      "phone_number": "+15551234567",
      "sip_config_id": "..."
    }
  ],
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-02-20T14:00:00Z"
}

Response Fields (Detail)

Field	Type	Description
id	uuid	Agent ID
name	string	Agent display name
active_stt_provider_id	uuid | null	Assigned STT provider
active_llm_provider_id	uuid | null	Assigned LLM provider
active_tts_provider_id	uuid | null	Assigned TTS provider
system_prompt	string | null	System prompt sent to the LLM
welcome_message	string | null	Message spoken at call start
voice_id	string | null	TTS voice identifier
language	string	Language code (e.g. en, es)
silence_threshold	float	Seconds of silence before end-of-turn detection
max_call_duration	integer	Max call length in seconds (0 = unlimited)
barge_in_sensitivity	string	low, medium, or high
interruptible	boolean	Whether the agent can be interrupted mid-speech
welcome_interruptible	boolean	Whether the welcome message can be interrupted
amd_enabled	boolean	Answering machine detection for outbound calls
tts_config	object | null	Provider-specific TTS settings
webhook_url	string | null	URL for call event webhooks
webhook_secret	string | null	Secret for webhook signature verification
is_active	boolean	Whether the agent is active
phone_numbers	array	Assigned phone numbers with SIP config references
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Create Agent

POST /agents

Request Body

{
  "name": "Sales Agent",
  "active_stt_provider_id": "uuid-of-stt-provider",
  "active_llm_provider_id": "uuid-of-llm-provider",
  "active_tts_provider_id": "uuid-of-tts-provider",
  "system_prompt": "You are a sales representative...",
  "welcome_message": "Hi there! Thanks for calling.",
  "voice_id": "rachel",
  "language": "en",
  "silence_threshold": 0.5,
  "max_call_duration": 600,
  "barge_in_sensitivity": "medium",
  "interruptible": true,
  "welcome_interruptible": false,
  "amd_enabled": false,
  "tts_config": { "speed": 1.0 },
  "webhook_url": "https://example.com/webhook",
  "is_active": true,
  "phone_numbers": [
    {
      "phone_number": "+15551234567",
      "sip_config_id": "uuid-of-sip-config"
    }
  ]
}

Request Fields

Field	Type	Required	Default	Description
name	string	Yes	--	Agent display name
active_stt_provider_id	uuid	No	null	STT provider to use
active_llm_provider_id	uuid	No	null	LLM provider to use
active_tts_provider_id	uuid	No	null	TTS provider to use
system_prompt	string	No	null	System prompt for the LLM
welcome_message	string	No	null	Message spoken when call starts
voice_id	string	No	null	TTS voice identifier
language	string	No	"en"	Language code
silence_threshold	float	No	0.5	Silence detection threshold (seconds)
max_call_duration	integer	No	0	Max call duration (0 = unlimited)
barge_in_sensitivity	string	No	"medium"	Barge-in sensitivity level
interruptible	boolean	No	true	Allow mid-speech interruption
welcome_interruptible	boolean	No	false	Allow welcome message interruption
amd_enabled	boolean	No	false	Enable answering machine detection
tts_config	object	No	null	Extra TTS provider config
webhook_url	string	No	null	Webhook endpoint URL
webhook_secret	string	No	null	Webhook signing secret
is_active	boolean	No	true	Whether agent is active
phone_numbers	array	No	null	Phone number assignments

Response

201 Created -- Returns the full AgentResponse object.

Provider IDs are validated against your tenant's configured providers. If a provider ID is invalid or belongs to the wrong type (e.g. passing an LLM provider ID as the STT provider), the API returns 400 Bad Request.

Update Agent

PUT /agents/{agent_id}

Partial updates are supported. Only include the fields you want to change.

Request Body

{
  "name": "Updated Agent Name",
  "system_prompt": "New system prompt...",
  "is_active": false
}

All fields from the create schema are accepted, but none are required.

Response

200 OK -- Returns the updated AgentResponse object.

Delete Agent

DELETE /agents/{agent_id}

Permanently deletes an agent and its phone number assignments.

Response

204 No Content -- No response body.

Get Agent by Phone Number

GET /agents/by-phone/{phone}

Look up the agent assigned to a specific phone number. Useful for routing logic.

Path Parameters

Parameter	Type	Description
phone	string	Phone number in E.164 format (e.g. +15551234567)

Response

Returns the full AgentResponse object, or 404 if no agent is assigned to that number.