Create a Voice Agent

This is the whole setup flow for a new voice agent: the Setup tab, what the rest of the tabs are for, and how to get from a draft to a live phone line. Nothing you do here can reach a real caller until you promote the agent, so it is safe to build it in pieces.

The form calls itself Voice Agent, but the underlying record is a campaign — that is why API paths and the occasional log line say campaigns. They are the same thing.

What you'll need

The agents:voice:manage permission. With only agents:voice:read you can open an agent and read it, but the Edit Voice Agent button will not be there.
A provisioned phone number, if this agent is going to use the telephone network — see Phone Numbers and Caller ID. You can create and test an agent without one; you just cannot put it on a line.
Anything you want the agent to use should exist first: document vector stores, published Tenant Brain knowledge, MCP servers, forwarding numbers. You can always come back and add them.

Start a new agent

Go to Agents → Agent Types → Voice Agents. This opens the shared Agents page filtered to voice (/agents?type=voice).
Click New Voice Agent, top right. (On the unfiltered All Agents page the same button reads New Agent; use the caret beside it to pick Voice agent.)
The form opens on the Setup tab with seven tabs across the top:

Tab	What lives there
Setup	Name, model, direction, delivery, instructions and greeting
Schedule	Limited-time prompts — instructions that apply only inside a date window
Voice	The voice itself, turn-taking, dead air, pronunciation
Telephony	Phone number, SMS number, forwarding, email identity, retention
Phone System	The PBX pre-call / post-call webhook integration
Tools	Tools, MCP servers, vector stores, memories, prompt components
Test & Deploy	Talk to the agent, place a test call, push it to production

A tab shows a small ! badge while something required on it is missing, and the header shows the same thing as jump-links — Add instructions and Assign phone number — which take you straight to the tab that owns the fix.

Fill in Basic Configuration

The first card on Setup:

Name (required) — how the agent appears in lists, on call records and in orchestration step pickers. Say what it does: "Main line — support", not "Voice 3".
Agent Mode — leave it on Production Agent (Default). Testing Agent deliberately disables MCP servers, memories and external tools, so the agent talks but cannot act. It is useful for rehearsing wording, and it is a trap if you forget you set it.
Delivery Method — Telephony (Phone System) for a real phone line, or Web (Browser-Based) for an agent people talk to in a browser instead. See Browser-Based Voice Agents.
Allow Chat — only meaningful for web delivery: it lets a person type alongside speaking.
Call Direction (required) — Inbound (Agent receives calls) or Outbound (Agent calls out). This is not cosmetic:
- An inbound agent owns the routing for its phone number. Promoting it is what makes that number ring this agent.
- An outbound agent is what orchestrations, the API and the Use Voice Agent page dial with.
- Only outbound calls get voicemail detection and extension dialling.
Multi-Lingual Support, Auto-Detect Language and Default Language — see Multilingual Calls and Language Detection. If you only work in one language, set Default Language and move on.
AI Model (required) — the picker offers four Gemini Flash models and defaults to Gemini 3.8 Flash (Google). If an agent was built on a model that has since been retired, the field shows it as (legacy) with a warning: that agent is failing every call until you pick a current model, and it will refuse to save until you do.
Thinking Level — how much internal reasoning the model does before it speaks. Higher is more careful and slower; on a phone call the delay is audible. Start at Medium - Balanced.
Verbosity — how much the agent says per turn. Low - Concise is usually right for voice.

Write the instructions

The second card, Instructions & Greeting, is where the agent actually comes from. The short version:

Agent Instructions (required) — who the agent is, what the call is for, what it must not do. The field shows a character and rough token count as you type.
Not sure where to start? Click Support line example or Outbound follow-up example in the card header to load a complete, editable starting point, or Build with AI to have one drafted from a description. Once the field has content that button becomes Optimize with AI.
Goals — one line per thing the call should achieve. Goals do not go into the prompt; they are what the performance dashboard scores calls against.
Static Greeting — the exact first sentence the agent speaks. Leave it empty and the agent opens in its own words.

There is a lot more worth knowing about this field — placeholders, the platform rules your instructions sit inside, and prompts that expire. See Instructions, Goals and Scheduled Prompts.

Pick a voice

Open the Voice tab and choose one. Type a phrase into Preview Text (or click Use agent greeting) and press the play button on any voice to hear it read that phrase. 52 voices are available. Details, and the rest of the tab: Voices, Greetings and Pronunciation.

Assign a phone number

Open the Telephony tab → Communication Settings:

Voice Phone Number — the line this agent uses. Assigning one is what flips the header badge from Not deployable yet to Approved · +1…. Once a number is selected the card shows the outbound caller ID callers will actually see, and whether a display name (CNAM) is set.
SMS Number — the number the agent texts from when it uses send_sms. A reply to that number is routed back into the live call.
Email From Name / Email From Address / CC / BCC / Email Signature — the identity the agent sends email under.

No numbers in the dropdown? A tenant admin provisions them at Settings (the gear icon) → Channels → Phone Numbers; the field links straight there.

Save it

The sticky bar at the bottom of the form holds:

Create Voice Agent on a new agent — this saves a draft. Drafts cannot receive a real inbound call and are not what an orchestration dials.
Save Changes once it exists.
Save & Push to Prod — saves, then asks you to confirm promotion. The confirmation is an in-page amber panel, not a browser dialog, and it tells you whether this is a first publish or an overwrite of the live copy, and what the agent will be able to do once live. Nothing is promoted until you click Promote to production.

Test before you promote

Go to Test & Deploy:

Talk to your agent — speak to it in your browser, with the real compiled prompt, tools and voice. Pick Draft (last saved changes) or Production under Version to test. Tools run for real.
Simulate Call — enter a phone number and the agent calls it, over the full telephony path, so you can hear transfers, voicemail detection and caller-ID lookup behave.

Full detail: Testing, Drafts and Going Live.

Troubleshooting

The header says "Not deployable yet". No phone number is assigned. Open Telephony and pick one — or, for a web-delivery agent, ignore it; it does not need a line.
"Save the voice agent first" on the Test & Deploy tab. Test calls need a saved record. Click Create Voice Agent and the panel appears.
Callers still reach the old behaviour after you saved. Saving updates the draft. Calls run the promoted copy — use Save & Push to Prod.
A real inbound call does not reach the agent at all. Inbound routing is registered from the promoted copy of an inbound agent. Check Call Direction is Inbound, the number is assigned, and the agent has been promoted. A number can only be live on one production inbound agent — promotion is refused if another one already has it.
The agent talks but never does anything. Check Agent Mode is not Testing Agent, and that the tool you expect is ticked on the Tools tab.