Agents
List and create voice agents with the SDK.
Agents are the conversational personas that run your calls.
List agents
const agents = await voice.agents.get();agents = client.agents()Create an agent
const agent = await voice.agents.create({
name: "Sales Outreach Bot",
systemPrompt: "You are a friendly sales assistant. Keep replies short.",
callingProvider: "local_voice",
language: "en",
model: "gpt-4o-realtime-preview",
temperature: 70,
voiceId: "alloy",
ttsVoice: "af_heart",
toolIds: ["tool_19ja0s"],
});agent = client.create_agent(
name="Sales Outreach Bot",
system_prompt="You are a friendly sales assistant. Keep replies short.",
calling_provider="local_voice",
language="en",
model="gpt-4o-realtime-preview",
temperature=70,
voice_id="alloy",
tts_voice="af_heart",
tool_ids=["tool_19ja0s"],
)Parameters
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name for the agent. |
systemPrompt / system_prompt | string | Yes | Core persona and behavior directive. |
callingProvider / calling_provider | string | Yes | Calling provider — local_voice or ultravox. |
language | string | Yes | Language code, e.g. en. |
model | string | Yes | Real-time LLM, e.g. gpt-4o-realtime-preview. |
temperature | integer | Yes | Sampling temperature, 0–100 (default 70). |
voiceId / voice_id | string | Yes | Voice profile identifier (e.g. alloy). |
ttsVoice / tts_voice | string | Yes | Text-to-speech voice name (e.g. af_heart). |
toolIds / tool_ids | string[] | Yes | Tool identifiers the agent may invoke mid-call. |
firstMessage / first_message | string | No | Opening line the agent speaks first. |
Where these values come from
Some fields are fixed sets; others you look up via the API.
| Field | Allowed values / source |
|---|---|
callingProvider | local_voice or ultravox |
model | gpt-4o-realtime-preview, gpt-4o-mini-realtime-preview, or ultravox-70B |
voiceId | The real-time model's built-in voice, e.g. alloy. Voice names depend on the chosen model/provider. |
ttsVoice | The text-to-speech engine voice, e.g. af_heart. |
language | A language code such as en. |
temperature | An integer 0–100 (default 70). |
toolIds | The id of each tool you've created. List them first — see below. |
There is no /models or /voices endpoint: model and callingProvider are
the fixed sets above, and voiceId / ttsVoice are provider-specific strings.
Get your tool IDs by listing tools, then pass the ids you want:
const { data: tools } = await voice.tools.get();
const toolIds = tools.map((t) => t.id);tools = client.tools()["data"]
tool_ids = [t["id"] for t in tools]Create a tool first with voice.tools.create(...) if you don't have any yet.