# 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](/help/voice-agents/phone-numbers).
  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

1. Go to **Agents → Agent Types → Voice Agents**. This opens the shared Agents
   page filtered to voice (`/agents?type=voice`).
2. 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**.)
3. 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 live |

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**:

1. **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".
2. **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.
3. **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](/help/voice-agents/web-voice-agents).
4. **Allow Chat** — only meaningful for web delivery: it lets a person type
   alongside speaking.
5. **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.
6. **Multi-Lingual Support**, **Auto-Detect Language** and **Default
   Language** — see [Multilingual Calls and Language Detection](/help/voice-agents/languages).
   If you only work in one language, set **Default Language** and move on.
7. **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.
8. **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**.
9. **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:

1. **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.
2. 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**.
3. **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.
4. **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](/help/voice-agents/instructions-and-scheduling).

## 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](/help/voice-agents/voices-and-speech).

## Assign a phone number

Open the **Telephony** tab → **Communication Settings**:

1. **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.
2. **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.
3. **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 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
  **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](/help/voice-agents/testing-and-promotion).

## Live-audio models (beta)

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, Google's turn detection and
a languages checklist, 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](/help/voice-agents/voices-and-speech),
[Turn-Taking](/help/voice-agents/turn-taking-and-timing),
[Tools and Knowledge](/help/voice-agents/tools-and-knowledge).

## 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 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 **Agent Mode** is not
  **Testing Agent**, and that the tool you expect is ticked on the **Tools**
  tab.

## Next steps

- [Instructions, Goals and Scheduled Prompts](/help/voice-agents/instructions-and-scheduling)
- [Tools, Knowledge and Memory](/help/voice-agents/tools-and-knowledge)
- [Transfers, Forwarding and the Duty Roster](/help/voice-agents/transfers-and-escalation)
- [Placing Outbound Calls](/help/voice-agents/campaign-usage)
- [Voice Agents Overview](/help/voice-agents/overview)