Agents

An Agent is a voice AI assistant with its own system prompt, provider configuration, knowledge base, and tools. Each agent can handle both WebSocket sessions and phone calls.

Create an Agent

BASH

curl -X POST https://ultravoice.us.inc/api/v1/agents/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Assistant",
    "system_prompt": "You are a professional sales assistant for Acme Corp. Be friendly and concise.",
    "welcome_message": "Hi! Welcome to Acme Corp. How can I help?",
    "workspace_id": "ws-abc-123",
    "language": "en"
  }'

Create Agent Parameters

"name" (string, required) — Display name for the agent
"system_prompt" (string, required) — Base system prompt defining personality and behavior
"workspace_id" (string, required) — Workspace this agent belongs to
"welcome_message" (string, optional) — Greeting spoken at the start of each call
"language" (string, optional) — Primary language code, default: "en"
"vad_threshold" (float, optional) — Voice activity detection sensitivity 0.3–0.8, default: 0.4
"silence_timeout_ms" (int, optional) — Silence before end-of-speech 200–1500ms, default: 300
"interrupt_enabled" (bool, optional) — Allow user to interrupt AI, default: true
"max_turns" (int, optional) — Maximum conversation turns 1–500, default: 100

List & Get Agents

BASH

# List all agents
curl https://ultravoice.us.inc/api/v1/agents/ \
  -H "Authorization: Bearer $TOKEN"

# Filter by workspace
curl "https://ultravoice.us.inc/api/v1/agents/?workspace_id=ws-abc-123" \
  -H "Authorization: Bearer $TOKEN"

# Get single agent
curl https://ultravoice.us.inc/api/v1/agents/{agent_id} \
  -H "Authorization: Bearer $TOKEN"

Provider Configuration

Each agent requires three providers: LLM (brain), ASR (ears), and TTS (voice).

BASH

curl -X POST https://ultravoice.us.inc/api/v1/agents/{agent_id}/providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "llm",
    "provider_name": "openai",
    "api_key": "sk-proj-...",
    "model_name": "gpt-4o-mini"
  }'

Provider Parameters

"provider_type" — "llm", "asr", or "tts"
"provider_name" — Provider ID, e.g. "openai", "deepgram", "elevenlabs"
"api_key" — Provider API key (encrypted at rest with AES-256)
"model_name" — Model to use, e.g. "gpt-4o-mini", "nova-2"
"voice_id" — Voice ID for TTS providers
"base_url" — Custom API endpoint for self-hosted models

⚠️

API keys are encrypted at rest using AES-256 encryption. They are never exposed in API responses.

Telephony Configuration

To enable phone calls for an agent, configure telephony credentials:

BASH

curl -X PUT https://ultravoice.us.inc/api/v1/agents/{agent_id}/telephony \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "twilio_account_sid": "ACxxxxxxxxxx",
    "twilio_auth_token": "your_auth_token",
    "twilio_phone_number": "+18005551000",
    "webhook_url": "https://ultravoice.us.inc/api/v1/telephony"
  }'

See the Telephony page for complete setup guides for Twilio.

System Prompt Best Practices

The system prompt is the most important configuration for your agent. A well-structured prompt includes:

Identity — "You are a [role] for [company]..."
Behavioral rules — Tone, response length, conversation style
Domain knowledge — Key facts, product info, policies
Boundaries — What the agent should NOT do
Edge cases — Escalation triggers, unknown question handling

💡

Keep responses to 1-3 sentences for voice. Long responses cause poor user experience in voice conversations.