> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Workflows

> Build structured, branching phone conversations with a visual node-based builder — greet, branch, collect data, call APIs, and route to a human, all on-script.

# Voice Workflows

A **Voice Workflow** is a visual state machine for a phone call. Instead of one
big system prompt that has to handle everything, you lay out the call as a graph
of **nodes** — each node is a single phase of the conversation (greet, branch,
collect an answer, call an API, hand off to a human, end the call). The call
walks the graph one node at a time.

The core idea: **only the current node is active.** At any moment the agent runs
just that node's prompt and its tools — nothing else. That keeps the agent
on-script and predictable, so a structured call (qualify a lead, book an
appointment, triage a support request) plays out the same way every time.

<Note>
  Voice Workflows are in **alpha**. Open them in **Agent Studio → the left sidebar → Workflow**.
</Note>

<Warning>
  **Replaces Tasks & Task Groups (deprecated).** Voice Workflows supersede the older
  voice **Tasks / Task Groups** data-collection feature, which is now **deprecated**
  and hidden from the Voice settings. A workflow's
  [Collector and Conversation nodes](/docs/voice/workflows/nodes) capture structured
  data the same way — plus branching, [knowledge lookups](/docs/voice/workflows/knowledge),
  and [tools](/docs/voice/workflows/tool). Existing agents that still use Tasks keep
  working; build new structured-collection flows as workflows.
</Warning>

## When to use a workflow vs a normal agent

A **normal voice agent** runs a single system prompt for the whole call. It's
open-ended and conversational — great when the caller can ask about anything and
you want the agent to improvise within its instructions.

A **Voice Workflow** is scripted and multi-step. Reach for one when the call has
a clear shape you want to enforce:

<CardGroup cols={3}>
  <Card title="Lead qualification" icon="filter">
    Greet, ask qualifying questions in order, branch on the answers, and route
    hot leads onward.
  </Card>

  <Card title="Appointment booking" icon="calendar-check">
    Collect a date and details, check availability via an API, and confirm — or
    offer alternatives.
  </Card>

  <Card title="Support triage" icon="headset">
    Classify the issue, gather the right details for that issue, and resolve or
    transfer to a human.
  </Card>
</CardGroup>

Because each phase exposes only its own prompt and tools, the agent can't wander
off-topic or skip a required question — the workflow holds it to the script.

<Info>
  Voice Workflows are a distinct, **voice-specific** feature. They are **not** the
  chat [Flow Editor](/docs/workflows) (a graph of Agent / Tool / Team nodes for
  chat and teams), and they are not [Crews](/docs/voice/crews) (multi-agent
  handoff on a live call). A Voice Workflow is one agent following a deterministic,
  branching script.
</Info>

## How it works in one minute

A few concepts power the whole thing. You don't need to master them to start —
the templates wire them up for you — but here's the mental model.

**Two prompt layers.** A **Global Prompt** (set in the Settings tab) holds the
shared personality and rules, and is prepended to every node. Each node then adds
its own **per-node prompt** for that phase. The agent at any moment runs
*Global Prompt + the current node's prompt*.

<Warning>
  An enabled Voice Workflow runs on the **workflow's** Global Prompt and node
  prompts — **not** the agent's Behavior-panel prompt. Edit your call's wording
  inside the workflow, not in the agent's Behavior panel.
</Warning>

**The Director.** After each caller turn, a fast LLM called the **Director**
does two jobs: it **extracts** the current node's declared variables from what
the caller said, and it picks which natural-language ("prompt") transition is
met. The Director is gated — it only runs when routing is genuinely ambiguous —
to keep latency low. You can change its model and temperature in Settings.

**Routing each turn (equation-first).** When deciding where to go next, the
engine resolves transitions in a fixed order: deterministic **equation** edges
(like `{{age}} > 18`) are checked in code first, first-true-wins; if none match,
the Director's chosen **prompt** edge is taken (once the node's required
variables are captured); otherwise a **global** node may take over; otherwise the
call stays put.

**Route-then-reply.** The engine first resolves the transition, *then* the
destination node produces the reply. So the next thing the caller hears already
belongs to the node they just moved into.

For the full picture, see [Transitions, Variables & the Director](/docs/voice/workflows/transitions).

## Quick start

<Steps>
  <Step title="Open the builder">
    Go to **Agent Studio → the left sidebar → Workflow** (it carries an **alpha**
    badge and appears in Developer Mode). The builder renders inline in the
    studio.
  </Step>

  <Step title="Start from a template (or blank)">
    Click **Templates** and pick **Lead Qualification**, **Appointment Booking**,
    **Support Triage**, or **Blank**. Templates drop in a working graph and
    auto-arrange it into a clean top-down tree, so you can edit rather than build
    from scratch.
  </Step>

  <Step title="Configure prompts and variables">
    Select a node to edit its prompt, First Message, and the variables it should
    **extract** or **require**, in the **Inspector**. Declare typed variables in
    the **Variables** tab, and set your shared **Global Prompt** and the Director
    in **Settings**. See [The Workflow Builder](/docs/voice/workflows/builder)
    and [Node Types](/docs/voice/workflows/nodes).
  </Step>

  <Step title="Validate">
    Click **Validate**. The **Issues** tab lists **errors** and **warnings**. Fix
    the errors.
  </Step>

  <Step title="Enable & Save">
    New workflows start **Disabled**. Flip the toolbar toggle to **Enabled** and
    click **Save** — the runtime reads your agent's current saved config, so an
    enabled, saved workflow runs on the next real call. The **Enabled** toggle is
    the single switch; there's no separate publish step to make it run. See
    [Going Live](/docs/voice/workflows/publishing).
  </Step>

  <Step title="Test call">
    Click **Test call** to talk to the workflow in a web call (no phone needed).
    It runs whatever you've **saved and enabled** — the same thing real callers
    get.
  </Step>
</Steps>

## Explore the docs

<CardGroup cols={2}>
  <Card title="The Workflow Builder" icon="diagram-project" href="/docs/voice/workflows/builder">
    The canvas, node palette, the Inspector / Variables / Settings / Issues
    tabs, and the toolbar.
  </Card>

  <Card title="Node Types" icon="circle-nodes" href="/docs/voice/workflows/nodes">
    Conversation, Collector, Condition, Set Variable, API Request, Knowledge, Tool,
    Transfer, End Call — and Global nodes.
  </Card>

  <Card title="Transitions, Variables & the Director" icon="code-branch" href="/docs/voice/workflows/transitions">
    Edges and conditions, equation operators, typed variables, and how the
    Director routes each turn.
  </Card>

  <Card title="API Request Node" icon="plug" href="/docs/voice/workflows/api-request">
    Call an external API mid-call, fill parameters from variables, and map the
    response back into the flow.
  </Card>

  <Card title="Workflow Templates" icon="table-list" href="/docs/voice/workflows/templates">
    Lead Qualification, Appointment Booking, Support Triage, and Blank — what
    each one ships with.
  </Card>

  <Card title="Publishing & Going Live" icon="rocket" href="/docs/voice/workflows/publishing">
    Validate, Save vs. Publish, the Enabled/Disabled toggle, and test calls.
  </Card>
</CardGroup>