The setup flow end to end — name, instructions, model, direction, number, save as a draft, test before anyone calls it.
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. An outbound agent has eight tabs
across the top; an inbound agent has seven, because Outbound only
appears when Call Direction is Outbound. Each tab answers one
question, in the order you meet it on a call:
Tab
What lives there
Setup
Who the agent is and how it connects: name, direction, delivery, phone number, environment, languages, model
Conversation
What it says: the opening and greeting, the instructions and goals, situations it reads only when one applies, and temporary instructions (scheduled text)
Voice
How it sounds: the voice, speaking style, fillers, background sound, pronunciation
Call handling
What happens on the line: turn-taking and silence, voicemail, transfers, and the PBX pre-call / post-call integration
Outbound agents only: the pre-dial brief, the first turn, the attempt policy and a preview of the brief
Data & privacy
How long this agent's transcripts are kept
Test & Deploy
Talk to the agent, place a test call, push it live
Links and bookmarks to the tabs these replaced (Telephony, Phone
System, Situations, Schedule) still work: they open the tab that now
holds those cards.
A tab shows a small ! badge while something required on it is missing, and
the header shows the same thing as jump-links — Add a name, Add
instructions and Assign phone number — which take you straight to the
tab that owns the fix.
Fill in the Setup tab
Setup has three cards: Call setup (how the agent is reached and whether
its tools run), Languages, and Model. Field by field:
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".
Call Direction — 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. Its pre-dial brief, first turn and attempt policy
are on the Outbound tab.
Only outbound calls get voicemail detection and extension dialling.
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.
Phone number — shown under Delivery Method for a telephony agent: the
line it answers (inbound) or calls from (outbound). Numbers are added under
Settings → Phone numbers; once one is chosen the field shows the caller
ID people will see. A web agent has no number and is never asked for one.
Allow Chat — only meaningful for web delivery. The line under the switch
says what visitors can do: today typing works in the web widget whichever
way it is set.
Environment — Production, Staging or Development. A label on
the agent: only Production agents count toward dashboards and statistics.
It takes effect when you save, without pushing live.
Tools during calls — leave it On (tools and MCP). Off: testing
without tools runs calls without the tools and MCP servers ticked on the
Tools tab and without voicemail-detection instructions, so the agent
talks but cannot act. Your ticks are kept: switch it back On and they
work again. Useful for rehearsing wording; a trap if you forget it. While
it is Off the header shows Call tools off, and the Tools tab says
Tools are off during calls with a link back to this switch.
Languages — 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 Gemini 3.8 Flash (Google)
(the default), Gemini 3.7 Flash (Google) and GPT-6 Luna (OpenAI). If
an agent was built on a model that has since been retired, the field shows
it as (legacy) with a warning. Calls on a retired model run on its
replacement, but the agent cannot be pushed live again until you pick a
current model.
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 card Instructions & Greeting, on the Conversation tab, is where
the agent actually comes from.
It reads in call order:
Opening — Who speaks first (the agent, or the caller) and the
Static Greeting, the exact first sentence the agent speaks. Hear it
plays the greeting in the agent's voice. While the caller speaks first the
greeting is kept but not used, and the field says so. On an outbound call
the agent waits for the person (Outbound → Wait for the person) and opens
with the greeting if they stay silent.
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.
Stuck on a blank field? Write with AI drafts one from the agent's name and
instructions; once the field has text it reads Improve with AI. It sits
beside:
Static Greeting and Goals (Conversation tab);
Speaking style, the filler lines and the tool-wait line (Voice tab);
Voicemail instructions or Exact message, and any line set to Exact
line: the check-in and the two transfer lines (Call handling tab);
the planner's instructions in the pre-dial brief (Outbound tab).
Add a hint if you like ("shorter, mention the free quote"). The draft appears
next to what is there and nothing changes until you choose Use this,
Replace or Add below; Undo puts your text back. It never invents a
price, an address or a phone number your instructions do not give. It is part
of Agent Prompt Studio, so it appears only when Agent Prompt Studio is turned
on for your workspace, and only for people who can edit the agent.
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, and 30 more where Gemini voices
are enabled for your workspace. Details, and the rest of the tab:
Voices, Greetings and Pronunciation.
Assign a phone number
The agent's Phone number is on the Setup tab, directly under
Delivery Method. It shows only for phone delivery: a web agent is reached
in the browser and has no number. Once a number is picked, a small panel under
it shows the outbound caller ID and display name (CNAM) that number
sends, with a link to change them on the number itself.
The identity the agent sends from lives on the Tools tab →
Sending identity:
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.
Set up outbound calls
On an outbound agent, open the Outbound tab. Its four cards follow a call
in order, and each opens with one sentence saying what it will do with the
values you have set, so you can check it before reading any field.
Before the dial · pre-dial brief. With Prepare a brief before every
outbound call on, the platform gathers what it knows about the contact
and writes a short plan for the agent before each dial: why we are calling,
what to confirm, how to open, what to leave on a machine.
Instructions to the planner — what to research and what to stress, in
your words.
What the planner is given — gathered for every call: the CRM dossier,
memories, history, business facts from the tenant brain and, if you tick
it, one web search about the contact's company.
What the planner may look up — what it may fetch on its own when it
wants more. A tool from one of your Connected servers (MCP) is never
ticked for you, and a ticked one runs for real when the planner calls
it, including on a preview. Each server shows only its ticked tools until
you click Show all … tools; the filter searches names and
descriptions.
What the plan may decide — whether the planner may advise not to call
(a skip shows as a row with its reason) and whether to offer calendar
slots.
Advanced — the planner's model, effort, depth, time budget and brief
size. The line beside the heading shows the values in use.
Switch the brief off and calls go out with the agent's own instructions.
Your planner settings are kept for when you switch it back on.
When they answer · first turn. How long the agent waits for the
person to speak before it opens. What happens when a machine answers
instead, and the pause before the message, is set on the Call handling
tab, in the Voicemail card.
Across attempts · attempt policy. No cap by default. Set a policy
to limit attempts in a window, space them out, and choose which outcomes
count. A policy also waits out the person's quiet hours, in their own
time zone: from their address, then their area code, then your
workspace's. A call that would land in their quiet hours is not placed,
both when it is queued and again just before dialling. A refused attempt
is recorded as a skipped call with the reason and when the contact
becomes eligible again. Remove the policy and then
Restore the policy brings back what you had.
Preview the brief. Enter a contact's email, phone or id to see the
plan the agent would get, and what the planner looked up, without placing
a call. The preview reads the saved agent, so save your changes first.
Cards 2 and 3 apply whether or not the brief is on.
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 Live — 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 Push Live.
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
Live (what callers reach today) under Version to test; an agent never
pushed live offers only the draft. Tools run for real. The left
side shows what is happening (Listening, Hearing you, Agent speaking) and a
meter of your microphone; the right side is the transcript as it happens,
with each tool call where it fired. After the test you get the number of
turns, the tools used and the time each stage took.
Place a test call — choose Draft (the default: the version you are
editing, as last saved) or Live (what callers reach today), 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.
Where a super admin has enabled Gemini Live voice agents (beta), the AI
Model list also offers Gemini 3.8 Live and Gemini 3.8 Live, extended
thinking. These are live-audio models: one Google model listens and speaks,
so the call has no separate speech-to-text or text-to-speech step, and the
form adapts — the Static Greeting is greyed out (the agent greets from your
instructions), the Voice tab offers Gemini voices and a languages checklist,
the Call handling tab offers Google's turn detection, and the Tools tab gains
Tools on live-audio calls.
The base model has no Thinking Level; the extended-thinking variant takes Low,
Medium or High. The header shows a Live audio badge, and live calls bill
under their own Live-audio voice minutes line. Details:
Voices, Greetings and Pronunciation,
Turn-Taking,
Tools and Knowledge.
Troubleshooting
The header shows "Assign phone number". No phone number is assigned.
Click it to open Setup and pick one under Delivery Method. A
web-delivery agent needs no line, and the header shows Web instead.
"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 Live.
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 Tools during calls
on Setup is On, and that the tool you expect is ticked on the
Tools tab.