Skip to main content
Agents are the core unit in TurnCall. An agent defines the personality, voice, and capabilities of your AI assistant.

​
Create an Agent

curl -X POST http://localhost:8090/v1/agents \
  -H "Authorization: Bearer tc_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "receptionist",
    "config": {
      "system_prompt": "You are a dental clinic receptionist...",
      "first_message": "Thank you for calling! How can I help?",
      "stt": {"provider": "deepgram", "model": "nova-2", "language": "en"},
      "llm": {"provider": "openai", "model": "gpt-4o-mini"},
      "tts": {"provider": "deepgram", "voice": "aura-2-helena-en"}
    }
  }'

​
Agent Config

{
  "name": "receptionist",
  "config": {
    "system_prompt": "You are a helpful receptionist...",
    "first_message": "Hello! How can I help?",
    "stt": {"provider": "deepgram", "model": "nova-3", "language": "en"},
    "llm": {"provider": "openai", "model": "gpt-4o-mini"},
    "tts": {"provider": "deepgram", "voice": "aura-2-helena-en"},
    "tools": [],
    "mcp_servers": [],
    "silence_timeout_ms": 800,
    "interruption_enabled": true,
    "smart_turn_detection": true,
    "voicemail_detection": {
      "enabled": true,
      "voicemail_message": "Please call us back..."
    },
    "server_url": {
      "url": "https://your-server.com/events",
      "events": ["*"]
    }
  }
}

​
Template Variables

Personalize agents per-call using {{variable}} placeholders: 
{
  "system_prompt": "You are helping {{customer_name}}. Their account is {{account_id}}.",
  "first_message": "Hello {{customer_name}}!"
}
Variables are rendered at call start via call-init or the API. See Server Events for how to dynamically inject variables.

​
Pipeline Mode

ModeDescriptionLatency
cascade (default)STT → LLM → TTS~800ms
s2sSpeech-to-speech via single model~300ms
Set pipeline_mode in the agent config: 
{
  "pipeline_mode": "s2s",
  "s2s": {"provider": "openai", "voice": "alloy"}
}
See Speech-to-Speech for details.

​
Voice Activity Detection

TurnCall uses Silero VAD for barge-in (interruption handling) and Smart Turn V3 (ML-based, local ONNX) for accurate end-of-turn detection. 
{
  "interruption_enabled": true,
  "smart_turn_detection": true,
  "silence_timeout_ms": 800
}

​
Voicemail Detection

For outbound calls, detect voicemail and leave a message: 
{
  "voicemail_detection": {
    "enabled": true,
    "voicemail_message": "Hi, this is TurnCall. Please call us back at..."
  }
}
Voicemail detection cannot be combined with pipeline_mode: "s2s".