Guided flows: scripted subagents¶

Last reviewed: 2026-09-24

A Guided flow is a subagent that runs a fixed, predictable sequence of steps — say something, listen for the answer, branch — instead of asking the AI model to improvise. Use one wherever the conversation is a required checklist: collect a claim number, confirm an address, book an appointment slot, walk a returns process.

While a guided flow runs, the expensive speech-to-speech model is paused entirely (it receives no audio and bills nothing); a lightweight speech-to-text service listens instead, and the flow speaks in the agent's own voice. When the flow finishes — or the caller asks for the agent — the model resumes with a summary of what happened and everything the flow captured, and the conversation continues naturally.

Creating one¶

1. Open the agent's stage, go to the Behavior tab, and find the subagent tab strip above the prompt (Main | … | +).
2. Click + and choose Guided flow (choosing Smart subagent creates the ordinary prompt-driven kind).
3. Name it and write the When to use hint — this is what the model reads when deciding to route the caller into the flow, exactly like a Smart subagent.

A guided tab shows a teal Guided badge, and instead of a prompt editor you get the step list.

Steps¶

Steps run top to bottom. Each step card can:

• Say — what the flow speaks at this step. {{variables}} render live, so "Booked for {{appointment_date}}" reads back what the caller gave you.
• Wait for a reply — turn this on to capture the caller's answer:
• Save the answer as — the session variable the answer is stored in. Everything else in the agent can use it afterwards (prompts, conditions, tool bindings).
• Answer type — Text takes the reply verbatim; Digits takes keypad entry (ended with #) or numbers spoken aloud; Choice matches one of the options you list — each option has an id, keywords (or a regex), and an optional keypad digit.
• Reprompt — what to say when the answer didn't match or the caller stayed silent. Timeouts and non-answers share one retry budget per step (set in Flow settings).
• Then — branch pills route to another step when a condition holds; the first true condition wins. With no matching branch the flow simply continues to the next step, and running past the last step hands back to the smart agent.
• Show on screen — when the stage has Multimodal UI enabled, pick a component from the attached catalogs to render alongside the spoken prompt. Prop values can reference {{variables}}, and they render live: when the caller answers by voice, the component re-renders showing what they said — the screen follows the voice automatically. Map answers → variables opens the standard answer-mapping dialog: point the component's answer at the step's Save the answer as variable and a tap on the screen fills the step exactly like a spoken answer (a form that fills several fields fast-forwards past every step it satisfies).

Flow settings¶

The collapsible Flow settings row above the steps holds:

• Escape phrases / escape key — saying "agent" (or pressing *) at any point hands the caller straight back to the smart agent, with a summary of where they were and what was already captured. The caller is never trapped.
• When a step gives up — after the retry budget runs out: hand back (default), end the session, or transfer to another subagent.
• Handback summary — the one message the smart agent receives when the flow completes. Reference the captured variables here ("Booked {{appointment_date}} for {{member_id}}") so the model can confirm without re-asking.
• Closing line — optionally spoken by the flow itself before control returns.

Choosing the technology a flow uses¶

Guided flows derive three sidecar services beside the agent's main model: the voice they speak with (also used by Payments and Secure Data Capture), the speech-to-text that listens while the model is paused, and the small matcher model used for fuzzy option matching. Defaults are matched to the agent's own provider (a Nova agent gets Transcribe + a Polly voice matched to its own; an OpenAI agent gets OpenAI services), and you can override them at two levels:

• Per agent — the stage's Properties → Auxiliary services section shows the selected defaults in the same service forms used by ordinary nodes, including voice previews and model dropdowns. Overrides are sparse: set just a voice or just a model and the rest of the derived default is kept.
• Tenant-wide — Settings → Tenant Settings → Auxiliary Services sets defaults for every agent in the tenant (see Auxiliary service defaults). A per-agent override always wins.

The matcher section also exposes Choice matching prompt and Guided entity extraction prompt. Expand a prompt to read or change its instructions, and use Use default prompt to restore it. The runtime still supplies the available choices and caller utterance.

What guided flows don't do¶

• They never take card numbers or other secrets — that stays with the Payments and Secure Data Capture capabilities, which a flow can hand off to and resume after.
• Return when conditions don't apply — a guided flow hands back by itself (completion, escape, or the retry ladder).
• They can't be converted to a legacy separate-call subagent — there is no prompt to convert.

Testing¶

Publish validation checks the script's structure (missing steps, branch targets that don't exist, a choice question with no options) before the flow can go live. Then test it like any subagent: open Preview, start a voice call, and say the routing phrase from your When to use hint. In the Activity Log the flow's turns are tagged as guided-script entries, and the orchestrator log shows the model pause and resume around the flow.