Agents

An agent bundles a system prompt, greeting, voice, and call-handling behavior. Every number and call belongs to an agent.

Create an agent

agent = client.agents.create(
    name="Support Bot",
    system_prompt="You are a helpful assistant. Be concise.",
    initial_greeting="Hi, this is Support. How can I help?",
    voice_id="female-1",
    voicemail_message="Hi, this is Support calling about your request. Please call us back at 555-0100.",
)

const agent = await client.agents.create({
    name: "Support Bot",
    systemPrompt: "You are a helpful assistant. Be concise.",
    initialGreeting: "Hi, this is Support. How can I help?",
    voiceId: "female-1",
    voicemailMessage: "Hi, this is Support calling about your request. Please call us back at 555-0100.",
});

Field	Purpose
`name`	Display name
`system_prompt`	Default instructions for all calls
`initial_greeting`	Opening line spoken when a call connects
`voice_id`	TTS preset (`female-1`) or Cartesia UUID
`transfer_number`	E.164 number to transfer calls to
`voicemail_message`	Spoken message left on outbound voicemail. Required if the agent should leave a mailbox message; without it the agent hangs up.
`owner_phone`	Owner number — calls from it enter “task mode”

Leaving voicemail

On outbound calls the pipeline detects a mailbox and leaves voicemail_message:

Greeting — “You’ve reached…”, “12418174 is not available”, “leave a message after the beep”. The agent does not press keys. It waits for the beep, speaks the message, and hangs up.
Record-key menu — “To disconnect, press 1. To record your message, press 2.” The agent presses 2, waits for the beep, then leaves the same message. If voicemail_message is unset it presses disconnect instead.

Include who you are, why you’re calling, and a callback number. Do not add “stay silent on automated messages” or “hang up if you hear press 1” to the system prompt — that fights the built-in handler.

client.agents.update(
    agent.id,
    voicemail_message="Hi, this is Alex calling about the apartment. Please call me back at 555-0100.",
)

await client.agents.update(agent.id, {
    voicemailMessage: "Hi, this is Alex calling about the apartment. Please call me back at 555-0100.",
});

Manage agents

client.agents.list()
client.agents.get(agent.id)
client.agents.update(agent.id, voice_id="male-1")
client.agents.delete(agent.id)

await client.agents.list();
await client.agents.get(agent.id);
await client.agents.update(agent.id, { voiceId: "male-1" });
await client.agents.delete(agent.id);

Per-call overrides: when making a call you can pass system_prompt, initial_greeting, and voice_id to override the agent defaults for that single call.

See the Create Agent endpoint in the API Reference.