# Overview (/docs/agents/voice-agents)

> For the complete documentation index, see [llms.txt](https://docs.tandemcx.ai/llms.txt). Any page on this site can be fetched as Markdown by appending `.md` to its URL.

A voice agent answers a phone call and holds a real conversation. It listens, decides
what to say, calls out to your systems when it needs to, and reports how the call ended
so your workflow can route on it.

You build agents under **Automations → Agents** in the left navigation. Calls reach an
agent in one of two ways:

- **From a workflow.** A [workflow](/docs/workflows) hands the call over using the **AI
  Voice Agent** node. Everything a workflow already does still applies: business-hours
  routing, screening, transferring afterwards. See
  [Using an Agent in a Workflow](/docs/agents/voice-agents/using-in-workflows).
- **Straight from a phone number.** Assign one of your organization's numbers, including a
  number on a [SIP trunk](/docs/overview/sip-trunks#route-a-trunks-calls), to the
  agent on its **Phone Numbers** card, and inbound calls to that number go directly to
  the agent with no workflow in between. Nothing routes on a disposition afterwards, and
  the **Set a workflow variable** built-in tool isn't offered, because there's no
  workflow waiting.

The same agent can also answer in a [chat widget](/docs/agents/chat-widget) on your
website. Which of the two an agent is for is its own **Channels** setting, on the
**Persona** card, and both are on by default. Settings that only mean something on a call
are marked **Voice only** in the editor: speech and turn-taking, the idle timer, call
limits, the telephony tools, keypad input, caller memory, phone-number routing, and post-call
analysis.
Switch **Voice** off and those settings are gone from the editor rather than marked, and
the agent needs no voice. See [Channels](/docs/agents/voice-agents/persona#channels).

## How a call flows through an agent

<Steps>
<Step>
### The call reaches the agent

An **AI Voice Agent** node passes the live call to the agent you selected, or the call
came in on a number assigned to the agent.

</Step>

<Step>
### The agent greets the caller

If you set a **Greeting**, the agent speaks it first. Otherwise it opens based on its
system prompt.

</Step>

<Step>
### The conversation runs

The caller speaks, the agent replies. Along the way it may search its knowledge base or
call one of its tools, such as running a workflow or hitting an API, and speak the result.

</Step>

<Step>
### The agent ends the call and reports a disposition

When the conversation reaches its natural end, the agent hangs up and reports one of the
**dispositions** you defined. A workflow that handed the call over continues from the
matching exit.

</Step>
</Steps>

## What you configure

The agent editor is a walk through the conversation, in the order one happens. A stepper
across the top lists the steps; the page shows **one step at a time**, and the stepper is the
only navigation. Steps are not locked in sequence: click any of them at any point, and
**Save Configuration** in the header commits the whole agent from wherever you are.

| Step                 | Cards on it                                                                                                                                                        |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Identity**         | **Persona**                                                                                                                                                        |
| **Routing & Memory** | **Phone Numbers**, **Chat Widgets**, **Returning Callers**, **Contacts**                                                                                           |
| **Conversation**     | **Brain**, **Voice & Speech**, **Knowledge**, **Custom Tools**, **Built-in Tools**, **Keypad Input**, **Skills**, **Steering Rules**, **Dispositions**, **Safety** |
| **Data Collection**  | **Data Collection**                                                                                                                                                |
| **Wrap Up**          | **Timeouts & Limits**                                                                                                                                              |
| **Post-call**        | **Post-Call Analysis**                                                                                                                                             |
| **Review**           | Every setting above, on one screen                                                                                                                                 |

Some steps are dropped when they would hold nothing, so some agents walk four steps rather than
seven. **Routing & Memory** goes for a chat-only agent in an organization that has neither chat
widgets nor Contacts. **Post-call** goes whenever post-call analysis isn't enabled for your
organization, or the agent has **Voice** switched off. **Data Collection** goes whenever data
collection isn't enabled for your organization.

The stepper does not score progress — there are no ticks and no "3 of 5 done", because most
of an agent is optional. The one thing it marks is the step holding the problem currently
blocking **Save Configuration**, which it rings in red as you type rather than waiting for a
failed save.

**Review** is the last step and the only place the whole agent is visible at once. It lists
every card, including the ones you haven't filled in, with the values you've set; required
fields that are still blank say so. Click a section heading to jump to the step that owns it.

Here is what each card holds:

| Card                   | What it controls                                                                       |
| ---------------------- | -------------------------------------------------------------------------------------- |
| **Persona**            | Name, channels, system prompt, goal, greeting, and this agent's own variables          |
| **Phone Numbers**      | Which of your numbers route inbound calls straight to this agent                       |
| **Chat Widgets**       | The website chat widgets that point at this agent                                      |
| **Returning Callers**  | Caller memory, the greeting returning callers hear, and reconnect after a dropped call |
| **Contacts**           | Whether the agent recognizes its caller, and may update their record                   |
| **Brain**              | Language model, reasoning, and conversation history                                    |
| **Voice & Speech**     | The voice it speaks in, whether callers can interrupt, and turn-taking                 |
| **Knowledge**          | A knowledge base it can search for facts                                               |
| **Dispositions**       | The outcomes the agent can report when a conversation ends                             |
| **Custom Tools**       | The actions you define: workflows, nodes, APIs, MCP servers, other agents              |
| **Built-in Tools**     | Call-control actions you switch on, such as transfers and keypad capture               |
| **Keypad Input**       | Whether a caller's keypresses reach the agent as an ordinary turn                      |
| **Skills**             | Named procedures the agent applies when the situation calls for them                   |
| **Steering Rules**     | Policies the agent's tool calls are checked against before they run                    |
| **Safety**             | Content protections and caller-PII redaction                                           |
| **Timeouts & Limits**  | Idle behavior, call-duration limits, and failure handling                              |
| **Data Collection**    | [Details the agent asks for](/docs/agents/voice-agents/data-collection) and records    |
| **Post-Call Analysis** | What to pull out of the transcript once the call ends                                  |

Only **Persona** and **Brain** have to be filled in to get an agent working.

Some cards are a single row inside a group — **Phone Numbers**, **Custom Tools**, **Built-in
Tools**, **Keypad Input**, **Skills**, **Steering Rules** and **Dispositions**. Each row
carries a gear glyph; click it and the row's editor opens in a side panel. **Chat Widgets** is
a row too, but a widget is its own record with its own editor, so it carries an
open-in-new-window glyph and takes you to the widget instead of opening a panel.
**Brain**, **Voice & Speech**, **Timeouts & Limits**, **Data Collection** and **Post-Call
Analysis** keep their main settings on the card and put the rest behind a button in the card's
header, which opens the same panel: **Conversation History**, **Speech Tuning**, **Reliability**,
**Data Collection Fields** and **Analysis Fields** respectively.

A single-channel agent shows fewer of these. With **Voice** switched off the call-only cards are
absent; with **Chat** off, **Chat Widgets** is. See
[Channels](/docs/agents/voice-agents/persona#channels).

Changes save when you click **Save Configuration**, and take effect on the agent's next call. A
call already in progress keeps the configuration it started with.

On an agent that uses [versioning](/docs/agents/voice-agents/versioning) — which every agent
created from now on does — **Save Configuration** writes to the draft you have open, and
publishing that draft is what changes the configuration callers get. On the agent's published
version you can still edit every field, but **Save as New Draft** replaces Save: your edits go to
a new draft, and the published version stays as it was. The name is the exception, because it
belongs to the agent rather than to a version, so a rename applies as soon as you save.

To hear a change before you save it, click **Call Agent** and talk to the agent in your
browser. See [Preview Calls](/docs/agents/voice-agents/preview-calls).

## Where to go next

<Cards>
    <Card
        title="Getting Started"
        href="/docs/agents/voice-agents/getting-started"
        description="Build a working voice agent and take a call with it."
    />
    <Card
        title="Preview Calls"
        href="/docs/agents/voice-agents/preview-calls"
        description="Talk to an agent in the browser, without a phone number or a workflow."
    />
    <Card
        title="Templates"
        href="/docs/agents/voice-agents/templates"
        description="Start from a reusable configuration, or save an agent as one."
    />
    <Card
        title="Persona"
        href="/docs/agents/voice-agents/persona"
        description="Name, system prompt, goal, greeting, variables, and dispositions."
    />
    <Card
        title="Voice & Speech"
        href="/docs/agents/voice-agents/voice-and-speech"
        description="How the agent sounds and how it takes turns."
    />
    <Card
        title="Brain"
        href="/docs/agents/voice-agents/brain"
        description="Model choice, reasoning, conversation history, and caller memory."
    />
    <Card
        title="Timeouts & Limits"
        href="/docs/agents/voice-agents/conversation"
        description="Idle behavior, call-duration limits, and failure handling."
    />
    <Card
        title="Tools"
        href="/docs/agents/voice-agents/tools"
        description="Let the agent run workflows and call your APIs."
    />
    <Card
        title="Built-in Tools"
        href="/docs/agents/voice-agents/built-in-tools"
        description="Transfers, keypad capture, and the other call-control actions."
    />
    <Card
        title="Keypad Input"
        href="/docs/agents/voice-agents/keypad-input"
        description="Send a caller's keypresses to the agent as an ordinary turn."
    />
    <Card
        title="Skills"
        href="/docs/agents/voice-agents/skills"
        description="Named procedures the agent follows when the situation calls for them."
    />
    <Card
        title="Knowledge Base"
        href="/docs/agents/knowledge-base/overview"
        description="Give the agent a searchable set of facts."
    />
    <Card
        title="Safety"
        href="/docs/agents/voice-agents/safety"
        description="Content protections, PII redaction, and steering rules."
    />
    <Card
        title="Contacts"
        href="/docs/agents/voice-agents/contacts"
        description="Recognize the caller, tell the agent who is on the line, and write back what it learns."
    />
    <Card
        title="Post-Call Analysis"
        href="/docs/agents/voice-agents/post-call-analysis"
        description="Extract sentiment, outcome, and your own fields from finished calls."
    />
    <Card
        title="Versioning"
        href="/docs/agents/voice-agents/versioning"
        description="Save drafts, publish the version that answers calls, and go back."
    />
    <Card
        title="Using an Agent in a Workflow"
        href="/docs/agents/voice-agents/using-in-workflows"
        description="Hand a call to an agent and route on the outcome."
    />
    <Card
        title="Security Review"
        href="/docs/agents/voice-agents/security-review"
        description="Ask Tandy to review a finished agent for risks a caller could exploit."
    />
</Cards>