Using an Agent in a Workflow

A workflow 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

The node's exits

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.

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.

Reading what the agent captured

If you turned on Set a workflow variable under the agent's 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. 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, 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.

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.

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 below), or give the agent a tool that looks the data up itself.

Next steps