> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callivox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating a voice agent
> Walk through the three tabs of the voice agent editor: identity and language, the prompt and tools, and what happens after the call ends.
Voice agents are built at **AI → Voice Agents → + New voice agent**. The editor has three tabs —
**General**, **Prompt & Tools** and **Post-call & chat actions** — and a save bar at the bottom. If
something required is missing, a warning strip at the top names it when you try to save.
## Tab 1 — General
### Identity
| Field | What to do |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Call direction** | Choose **Outbound** (the agent dials) or **Inbound** (the agent answers). New agents start on **Outbound**. |
| **Name** | Required. What you'll call the agent in the dialer, in call logs and in filters. |
| **Phone number** | Pick from the numbers available to your workspace. An inbound agent needs one — it's the number customers ring. |
One number, one agent. If you want a second inbound agent, give it a different number.
### Language and voice
| Field | What to do |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Language** | Required. The language the agent speaks. Start typing to filter the list. |
| **Secondary languages** | Optional. Add the other languages your callers use and the agent can follow them there. |
| **Voice** | Required. The voice the agent speaks with. Voices are filtered by the language you picked, so choose the language first. Press the play button on an option to hear it. |
Picking a voice is worth doing carefully — see [Voices and tuning](/voice-agents/voices-and-tuning).
### Ambient sound and timezone
| Field | What to do |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ambient sound** | Background atmosphere on the call: **Off**, **Office**, **City**, **Forest**, **Crowded room**, **Cafe** or **Nature**. |
| **Ambient sound volume** | From 0 (silent) to 1 (loud). |
| **Timezone** | The timezone the agent reasons in when it talks about dates and times. Defaults to `UTC` — set it to where your customers are, or the agent will offer them appointments at the wrong hour. |
A quiet **Office** ambience at a low volume makes long silences feel less like a dropped call.
Leave it **Off** if you'd rather the line stay clean.
### Advanced settings
A collapsed card holding the call timing, turn-taking and speech tuning. New agents start on
recommended values, so you can leave it closed. See
[Voices and tuning](/voice-agents/voices-and-tuning) for what each one does.
## Tab 2 — Prompt & Tools
### Conversation start
| Field | What to do |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Who speaks first** | **AI assistant** or **Customer**. For outbound calls the agent almost always speaks first. |
| **Initial message** | The opening line. Say who is calling and why, in one sentence. |
| **Knowledge base** | Optional. Lets the agent answer from your own documents — the same knowledge bases your chatting agents use. See [Prompt, knowledge and tools](/ai-agents/prompt-knowledge-and-tools). |
| **Knowledge base mode** | **Function call** lets the agent look something up mid-call when it decides it needs to. **Prompt** puts the material in front of it from the start. |
### Call variables
Key/value pairs the agent knows before the call begins — a customer's name, an order number, an
appointment time. Declare them here and refer to them in the prompt. Whoever places the call fills
in the values; the dialer pre-fills the exact variables this agent declares.
### Custom tools
Chips for the tools you've built under **AI → Tools / Functions**. Tick the ones this agent may
call. A tool that's still being set up for voice shows as a greyed-out chip — wait a moment and
reload.
### Built-in tools
Actions Callivox provides. Add the ones the agent needs:
| Tool | What it does |
| ------------------------ | -------------------------------------------------------------------- |
| **End call** | Lets the agent hang up when the conversation is finished. |
| **Call transfer** | Passes the call to a phone number you give it. |
| **Warm call transfer** | The same, but the agent briefs the receiving person first. |
| **Collect keypad** | Captures digits the caller types, such as a reference number. |
| **DTMF input** | Sends keypad tones — for navigating an automated menu on a transfer. |
| **Calendar integration** | Books an appointment. Needs a calendar API key and an event slug. |
| **Assistant transfer** | Hands the call to another voice agent. |
Each tool has its own required fields, and the editor won't let you save until they're filled in.
### System prompt
The agent's standing instructions, in Markdown. Everything on
[writing a good prompt](/ai-agents/prompt-knowledge-and-tools) applies, with a few things that
matter more on a call than in a chat:
* **Write for the ear.** No bullet lists, no headings in the output, no URLs read aloud. Short
sentences the agent can say in one breath.
* **Give it an opening and an ending.** How to greet, and how to close a call politely.
* **Tell it what to do with silence and confusion.** "If the caller doesn't respond, check whether
they're still there once, then end the call."
* **Say when to hand over.** Name the situations where it should transfer rather than push on.
* **Spell out numbers and dates the way you want them spoken.** Otherwise you get whatever the
agent decides.
Read your prompt out loud before you save it. If you wouldn't say it on the phone, don't ask the
agent to.
## Tab 3 — Post-call & chat actions
What happens once the call ends.
### Post-call data schema
"Structured fields extracted from the call transcript." Add a row per fact you want pulled out of
every call — `callback_time`, `interested`, `order_number`. Each row takes a name, a type (text,
number or true/false) and a short description telling the agent what to look for.
Field names must be lowercase letters, digits and underscores, 3 to 16 characters. Descriptions
need at least 3 characters.
These fields show up on the call afterwards as **Variables** in
[the call detail pane](/voice-agents/call-logs).
The switch **Run post-call evaluation** has the agent score how the call went. Results appear in
the **Evaluation** card on the call.
### Webhook
Push each finished call to a system of yours.
| Field | What it does |
| ---------------------------------- | ------------------------------------------ |
| **Webhook active** | Turns the webhook on. |
| **Webhook URL** | Where to send it. |
| **Send webhook only on completed** | Skip calls that failed or went unanswered. |
| **Include recording in webhook** | Attach the audio. |
### Chat conversation ended
For agents that also follow up in chat: a **Conversation inactivity timeout (minutes)**, a
**Retrigger on conversation end** switch, and a **Conversation ended webhook URL**.
## Before you save
Name, Language and Voice are required. Call length is capped between 20 seconds and 20 minutes.
Save, then use **Test call** in the editor header to ring yourself — it opens the dialer with this
agent already selected. See [Call logs](/voice-agents/call-logs).
**Delete** on a voice agent is permanent and asks "Delete this voice agent?" before it goes. Its
past calls stay in the call log.
## Next steps
Choose a voice, and understand the advanced settings.
Listen back, read the transcript, and place a call.