create_agent
Create a voice AI agent with just a name and instructions. Automatically applies provider defaults for brain, voice, and transcriber, enabling immediate deployment.
Instructions
Create a new voice AI agent.
Only name and instructions are required. All provider defaults are
applied server-side — if you don't specify brain/voice/transcriber, the
platform picks its current production defaults (Phantom brain, Cartesia
sonic-3 voice with Fatima — Arabic, Soniox stt-rt-v4 transcriber with
EN+AR language hints — pairs natively with Fatima for code-switching).
Behavior defaults: turn_detection.mode=stt (Soniox owns endpointing),
preemptive_generation=true, recording on with 30-day retention,
post-call analysis on (PassFail rubric).
Brain (LLM) providers
phantom — default, Neuratel AI (~178ms TTFT)
model: "phantom"
groq — Groq fast inference (~443ms TTFT)
model: "meta-llama/llama-4-scout-17b-16e-instruct" (recommended)
model: "llama-3.1-8b-instant" (fastest)
model: "openai/gpt-oss-20b" (with reasoning)
openai — OpenAI GPT (~583-1213ms TTFT)
model: "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"
model: "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano"
xai — xAI Grok (~93-180ms TTFT)
model: "grok-4-1-fast-non-reasoning" (recommended)
model: "grok-4.20-0309-non-reasoning"
Voice (TTS) providers
cartesia — default, best quality (~37ms latency)
voice_model: "sonic-3"
voice_id: "731ace69-ee17-41bc-8c6f-665c9f1db95c" (default, Fatima — Arabic; pairs with default Soniox EN+AR hints)
voice_speed: float or preset ("fastest","fast","normal","slow","slowest")
elevenlabs — most expressive (~71ms latency)
voice_model: "eleven_flash_v2_5"
voice_id: any ElevenLabs voice ID
voice_speed: float (0.25–4.0), stability via config dict
phantom — Neuratel native voices (~100ms latency)
voice_model: "phantom-english-speech-preview" or "phantom-arabic-speech-preview"
voice_id not used; set voice name in config: {"voice": {"voice": "aria"}}
English voices: aria, bella, claire, alex, david, marcus
Arabic voices: omar, tariq, layla, nour
Transcriber (STT) providers
soniox — default, Soniox v4 with semantic end-of-utterance built in
transcriber_model: "stt-rt-v4" (single unified model, 60+ languages)
Default language_hints: ["en", "ar"], language_hints_strict: true
When transcriber.provider="soniox", the worker auto-routes turn_detection.mode to "stt" (Soniox owns endpointing)
Requires per-org soniox_api_key (BYOK)
deepgram — best accuracy for telephony-only English (~83ms latency)
transcriber_model: "nova-3" (recommended), "nova-3-medical"
language: BCP-47 e.g. "en-US", "ar", "multi" (auto-detect)
openai — GPT-4o powered (~138ms latency)
transcriber_model: "gpt-4o-mini-transcribe"
language: ISO code e.g. "en", "ar", "es"
phantom — Neuratel native STT
transcriber_model: "phantom-stt-v1"
language: "auto" (auto-detect)
Advanced config
Use the config dict for anything not covered by named params. It accepts
the full agent config structure — same shape as get_agent returns.
config={
"turn_detection": {
"mode": "semantic_vad", # or "vad"
"min_delay": 0.5,
"max_delay": 6.0,
"endpointing_mode": "dynamic" # or "fixed"
},
"timeout": {
"enabled": True,
"trigger_seconds": 15.0,
"warning_messages": ["Are you still there?"],
"final_message": "Goodbye!"
},
"background_audio": {
"ambient": {"enabled": True, "source": "office_ambience", "volume": 0.3},
"thinking": {"enabled": True, "source": "keyboard_typing", "volume": 0.5}
},
"tools": {
"rag": {"enabled": True, "knowledge_base_ids": ["kb-id"], "top_k": 5},
"voicemail": {"enabled": True, "action": "hangup"},
"hangup": {"enabled": True, "keywords": ["goodbye", "bye"]}
},
"transfer": {
"enabled": True,
"mode": "blind",
"destinations": [{"name": "Support", "number": "+15551234567",
"description": "Human agent", "keywords": ["human", "agent"]}]
},
"analytics": {
"recording": {"enabled": True},
"summary": {"enabled": True},
"success_evaluation": {
"enabled": True,
"criteria": "Did the agent resolve the issue?",
},
},
"interruption": {
"enabled": True,
"min_duration": 0.5,
"min_words": 0,
"false_interruption_timeout": 2.0,
"resume_false_interruption": True
}
}Returns: agent id, name, status, brain provider/model, voice provider.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| tags | No | ||
| config | No | ||
| language | No | ||
| voice_id | No | ||
| max_tokens | No | ||
| brain_model | No | ||
| description | No | ||
| temperature | No | ||
| voice_model | No | ||
| voice_speed | No | ||
| instructions | Yes | ||
| first_message | No | ||
| brain_provider | No | ||
| voice_provider | No | ||
| max_call_duration | No | ||
| transcriber_model | No | ||
| interruption_enabled | No | ||
| transcriber_provider | No | ||
| first_message_delay_ms | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||