# Using an Agent in a Workflow (/docs/agents/voice-agents/using-in-workflows)

> 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 [workflow](/docs/workflows) can hand a live call to a voice agent, which means everything
a workflow does before and after the conversation still applies. You can check business
hours first, gather an account number, hand off to the agent, and then route on how the
conversation ended.

The handover is the **AI Voice Agent** node.

You can also assign a phone number, or a number on a SIP trunk, directly to an agent from its
**Phone Numbers** card, in which case no workflow is involved. Do that for a line that is only
ever the agent; use a workflow when anything has to happen before or after the conversation,
because a direct-assigned call has nothing to route a disposition into.

## Hand a call to an agent

<Steps>
<Step>
### Add the node

In the workflow editor, add an **AI Voice Agent** node (it's in the **Bot** category) and
connect it into your flow.

</Step>

<Step>
### Choose the agent

Set the **Agent** field. The dropdown lists the agents in your organization.

</Step>

<Step>
### Wire up the exits

Choosing an agent fills in the **Dispositions** field automatically from that agent's
configuration, and each disposition becomes an exit on the node. Connect each one to whatever
should happen next.

<Callout type="info">
    You don't type dispositions here; they're read from the agent. To change them, edit the agent's
    [Dispositions card](/docs/agents/voice-agents/persona#dispositions) and re-select the agent on
    the node.
</Callout>

</Step>

<Step>
### Publish and test

Publish the workflow and call the number it's routed to. This is the check that routing and
the node's exits are right. To test how the agent itself sounds, a
[preview call](/docs/agents/voice-agents/preview-calls) is faster and needs neither.

</Step>
</Steps>

## The node's exits

| Exit                | Taken when                                                                     |
| ------------------- | ------------------------------------------------------------------------------ |
| One per disposition | The agent ended the call and reported that disposition.                        |
| **default**         | The call ended without a more specific disposition, or the agent defines none. |
| **fallback**        | Something went wrong reaching or running the agent.                            |

Wire all three kinds. `default` and `fallback` firing into nothing is how a call ends in
silence:

- **`default`** is the normal catch-all. Route it the way you'd route an unremarkable ending:
  a closing message, or straight to **Disconnect**.
- **`fallback`** is the error path. Route it to a human or a voicemail, not to another attempt
  at the agent.

## Pass values to the agent

The node's **Pass to agent** list hands the agent values that change from call to call: a
customer id, an account tier, the result of a lookup the workflow already did. Each row is a
**name** and a **value**.

| name          | value          |
| ------------- | -------------- |
| `customer_id` | `$(lookup.id)` |
| `tier`        | `$(crm.tier)`  |

The **value** is templated against this workflow's own variables, so it can carry anything the
flow has already worked out. The **name** is what the agent calls it: reference it as
`{{vars.customer_id}}` in the agent's prompt, greeting, thinking cue, disposition
descriptions, or an integration tool's constant parameters.

Three things to know before relying on it:

- **A name the workflow didn't pass reads as empty, and does not fail the call.** One agent can
  be reached from several workflows that pass different things, so write the prompt so a blank
  reads sensibly.
- **The values are fixed at the handover.** A workflow that resumes afterwards cannot change
  what the agent already saw.
- **Don't pass a credential this way.** These reach the agent's prompt, and therefore the
  model's context and the transcript. Store it as a secret and reference it from an integration
  tool instead.

Limits: 25 values, 2KB each, 16KB in total, counted as UTF-8 bytes. Over any of them the
handover fails and the flow takes the node's error exit rather than handing over a
half-populated call. See [Secrets &
Variables](/docs/overview/secrets-and-variables#values-for-a-single-call).

## Reading what the agent captured

If you turned on **Set a workflow variable** under the agent's [built-in
tools](/docs/agents/voice-agents/built-in-tools), the values the agent recorded are written into the
workflow's variables before the AI Voice Agent node takes its exit. A condition node placed
immediately after the agent can branch on them straight away.

Two limits apply: at most 20 variables per call, and 512 characters per value. A call that goes
over either limit arrives with **no** variables rather than some of them, because a workflow
routing on half of what the agent captured would be worse than one routing on none.

Variables only cross back on a call that reached the agent _from_ a workflow. On a phone number or
SIP trunk pointed straight at the agent there is no workflow waiting, so the tool is not offered at
all.

## Patterns

**Screen before you hand over.** Time-of-day checks, blocklists, and language selection are
cheaper and more predictable as workflow nodes than as agent instructions. Put them before the
handover.

**Follow the agent, don't duplicate it.** Anything the agent should do _during_ the
conversation belongs in the agent as a [tool](/docs/agents/voice-agents/tools). Anything that
happens _after_ the conversation ends belongs in the workflow, off the matching exit.

**Route escalation as a disposition.** Give the agent an `escalated` disposition and wire that
exit to a transfer. The agent decides it's out of its depth; the workflow decides where the
call goes.

**One agent, several workflows.** An agent isn't owned by a workflow. A single `Billing Triage`
agent can serve the main line, the Spanish line, and the callback queue — each workflow routes
its exits differently.

**Match dispositions to what happens next.** If two dispositions route to the same node, they
probably want to be one disposition; if one exit needs an `if` after it to decide what to do,
it probably wants to be two.

## Troubleshooting

**The node's Dispositions field is empty.** The selected agent has no dispositions defined. Add
them on the agent's [Dispositions card](/docs/agents/voice-agents/persona#dispositions), then
re-select the agent on the node so the exits refresh.

**I added a disposition on the agent but the node's exits didn't change.** Re-select the agent in
the node's **Agent** field — the exits are populated when the agent is chosen.

**Every call takes the `default` exit.** The agent isn't reporting a disposition that matches.
Check that its disposition descriptions read as conditions for choosing them, and that they
cover how calls really end. See
[Persona](/docs/agents/voice-agents/persona#troubleshooting).

**Calls take the `fallback` exit.** The agent couldn't be reached or failed mid-call. Confirm the
agent still exists and that its saved model is still available on its
[Brain card](/docs/agents/voice-agents/brain).

**The caller hears silence after the conversation ends.** An exit isn't wired. Every exit,
including `default` and `fallback`, needs somewhere to go.

**The agent answers but knows nothing about what the workflow already gathered.** Nothing
crosses over automatically. Either fill in the node's **Pass to agent** list, which hands the
agent named values it reads as `{{vars.<name>}}` (see [Pass values to the
agent](#pass-values-to-the-agent) below), or give the agent a
[tool](/docs/agents/voice-agents/tools) that looks the data up itself.

## Next steps

<Cards>
    <Card
        title="AI Voice Agent node reference"
        href="/docs/workflows/reference/category/bot/aiVoiceAgent"
        description="The node's fields and exits in full."
    />
    <Card
        title="Error Handling"
        href="/docs/workflows/error-handling"
        description="How fallback exits fit into a workflow's error strategy."
    />
    <Card
        title="Persona"
        href="/docs/agents/voice-agents/persona"
        description="Define the dispositions these exits come from."
    />
</Cards>