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

# VoiceFlow Studio Features

> Per-stage controls in the VoiceFlow studio canvas — entry/exit prompts, security gates, extraction fields, tools, and rail guards

The VoiceFlow studio gives you fine-grained control over every stage of a call. This page covers the advanced fields you can configure on each node in the canvas, what they actually do during a live call, and when to use each one.

For the basics of creating a VoiceFlow, see [VoiceFlows](/guides/voiceflows). This guide assumes you already have a flow and want to tune it.

## How a stage runs

A VoiceFlow is a graph of stages. During a live call, the runtime is always "in" exactly one stage. The agent's behavior in that stage is shaped by:

1. The **stage instructions** — the system prompt for the conversation LLM.
2. **Outcomes** — what the agent listens for; firing one transitions the call to a new stage.
3. **Optional advanced fields** — described below. Most flows don't need every one.

Click any node on the canvas to open the **Properties Panel** on the right. That's where you configure everything below.

## Stage instructions

The most important field. This is the system prompt your agent reads while in this stage.

Write it like you'd brief a human colleague: who they are, what to do, what to capture, what to avoid. Be specific.

<Tip>
  Avoid vague instructions like *"be helpful and professional"*. Instead: *"Confirm the caller's name and date of birth, then ask what they need help with. Do not give medical advice — refer to a clinician."*
</Tip>

## Outcomes

Each conversation node has one or more outcomes — the named paths leading out. The Stage Evaluator (a fast LLM running alongside the conversation) decides which outcome fired based on what was said this turn.

For each outcome, set:

* **Label** — what shows on the canvas edge.
* **Condition** — natural-language description of when this outcome should fire (e.g. "Caller agreed to book an appointment"). The Evaluator uses this to decide.

A node with no outcomes is a dead end. The runtime requires at least one outgoing edge per non-terminal node.

## Entry prompt

Open the Properties Panel and find **Advanced → Entry prompt**.

Text injected into the agent's prompt the first turn after the call enters this stage. Use it for context the agent needs only on entry — for example:

> *"The caller has just confirmed they're an existing patient. Now collect their reason for calling."*

The runtime adds this as `[Stage Entry]: ...` to the conversation prompt only on the first turn of the stage.

## Exit prompt

**Advanced → Exit prompt**.

Text the agent reads on the *last* turn of the stage as a "before you leave, make sure to..." reminder. The runtime injects it as `[IMPORTANT — Correct on this turn]` on the next turn.

> *"Make sure the caller has confirmed the appointment date before ending."*

## Max turns

**Advanced → Max turns**.

Hard safety cap on how many user turns the stage can run. When reached, the runtime auto-advances to the first outcome's target.

| Stage type              | Recommended max turns |
| ----------------------- | --------------------- |
| Greeting                | 2-3                   |
| Confirmation / closing  | 2-3                   |
| Triage / data capture   | 4-6                   |
| Complex troubleshooting | 6-8                   |

<Warning>
  Always set this. Without a cap, a misbehaving stage can spin indefinitely.
</Warning>

## Extraction fields

**Advanced → Extraction fields**.

A list of `snake_case` field names you want the agent to capture as the conversation flows — for example `caller_name`, `phone_number`, `appointment_time`.

The runtime injects this as `[Capture if mentioned]: ...` into the agent's prompt and tells the Stage Evaluator to look for these fields specifically. Captured values land in the call's `extracted_fields` and are saved to the post-call record.

<Note>
  Extraction fields are *opportunistic* — the agent listens for them but won't interrogate the caller. Use **Output schema** below if a field is *required* before the stage can complete.
</Note>

## Output schema

**Security → Output schema**.

A list of fields that MUST be captured before the stage is allowed to advance. The Stage Evaluator refuses to mark the stage `completed` until every name in the list is present.

> Example: a "Book appointment" stage with `output_schema: ["appointment_time", "caller_name", "phone_number"]` will not transition out until all three are captured.

This is the right field to use when downstream stages or tools depend on those values being present.

## Security gates

**Security → Security gates**.

Prerequisite gates (e.g. `["identity_verified"]`) that must already be in `extracted_fields` before the runtime allows entry to this stage. If a gate is missing, the transition is blocked and the call stays in the previous stage.

Use this with **Output schema** on an upstream stage to enforce flow:

<Steps>
  <Step title="Verification stage">
    Set `output_schema: ["identity_verified"]` so the stage cannot complete until verification succeeds.
  </Step>

  <Step title="Sensitive stage">
    Set `security_gates: ["identity_verified"]`. The runtime will not enter this stage unless verification has been captured upstream.
  </Step>
</Steps>

## Tools

Stage tools let the agent take actions during the call — book a slot, look up a knowledge base, send an SMS, transfer to a human.

Drag a tool from the **Node Sidebar** onto a stage. For each attached tool, you can set:

* **Tool prompt** — natural-language guidance for *when* the agent should use this tool. Written like *"Use when the caller has agreed on a time and confirmed their name and phone number."* The runtime appends this to the stage system prompt as a `## Tool Guidance` section.
* **Configuration** — tool-specific options (calendar id, knowledge-base ids, SMS body template, etc.)

### Built-in tools

| Tool ID            | What it does                              | Common use                                |
| ------------------ | ----------------------------------------- | ----------------------------------------- |
| `appointment`      | Books a slot in a connected calendar      | Reception, sales follow-up                |
| `knowledge_lookup` | Searches an internal knowledge base       | FAQ-heavy flows                           |
| `web_search`       | Searches the open web                     | Public-data lookups (rare)                |
| `send_message`     | Sends an SMS or WhatsApp                  | Booking confirmations, links              |
| `send_email`       | Sends an email                            | Receipts, summaries                       |
| `transfer_call`    | Hands off to a human or another VoiceFlow | Safeguarding, escalations                 |
| `send_dtmf`        | Sends a touch-tone digit                  | Navigating an upstream IVR after transfer |

<Tip>
  Place a tool on **a specific stage** when it's only relevant there (e.g. `appointment` on the booking stage). Place it on the **Global node** when it should be available from any stage (e.g. `transfer_call` so the caller can ask for a human at any time).
</Tip>

## Transfer destinations

For `transfer_call` terminal nodes, set the **Transfer target** in the Properties Panel:

* **Human** — a labelled queue or specific phone number. The runtime hands the live call off when this terminal is reached.
* **Workflow** — another VoiceFlow. AI-to-AI handoff, useful for escalating from a frontline triage flow to a specialist flow.

## Global node — identity and rail guards

The **Global node** sits at the top of the canvas. Click it to set:

### Identity

The agent's persona — name, role, tone, expertise. This applies to every stage. Be specific.

> *"You are Sarah, the appointment coordinator at Acme Dental in Boston. You speak warmly and unhurriedly. You know dental insurance terminology but you do not give clinical advice."*

### Rail guards

Always-active safety boundaries. Each rail guard has:

* **Label** — short name (e.g. *"No medical advice"*).
* **Instructions** — what the agent must never do (e.g. *"Never diagnose, suggest treatments, or interpret symptoms. Refer all clinical questions to a clinician."*).
* **Action** — what to do when the guard fires:
  * `block` — refuse and redirect.
  * `warn` — flag the violation in analytics but continue.
  * `escalate` — immediately transfer to a human queue.

Rail guards are injected into every turn's prompt as a `## Rail Guards` section — they apply globally regardless of stage.

<Warning>
  For regulated industries (medical, legal, financial), always include at least one `block` rail guard. The AI generator includes a sensible baseline; review it before going live.
</Warning>

## Common recipes

### Booking flow with consent gate

```
Stage 1 — Triage
  output_schema: ["consent_to_share"]
  extraction_fields: ["caller_name", "phone_number"]

Stage 2 — Book
  security_gates: ["consent_to_share"]
  output_schema: ["appointment_time"]
  tools: [appointment]
```

The "Book" stage cannot be entered until consent is captured upstream.

### Safety-first medical triage

```
Global:
  rail_guards:
    - "No medical advice" → block
    - "Safeguarding override" → escalate

Greeting → Triage (max_turns: 4) → Routing → 4 paths
  Path D = transfer_call to MASH duty line
```

### FAQ agent

```
Greeting → Q&A:
  tools: [{
    toolId: "knowledge_lookup",
    toolPrompt: "Use for any factual question about our services",
    config: { knowledgeBaseIds: [...] }
  }]
  exit_prompt: "Confirm the caller's question is answered before ending."
  max_turns: 8

Q&A → end_call
```

## Validating your flow

Click **Validate** in the studio toolbar to get:

* A plain-English **summary** of every stage, tool, and rail guard.
* A 0-100 **health score** across coverage, clarity, safety, completeness, and UX.
* Specific **suggestions** for improvement, with severity (critical / warning / info).
* 4-6 **test scripts** — sample call transcripts you can run mentally or via Test Call.

Validation results are cached per-flow — re-clicking on an unchanged flow is instant. Click **Regenerate** to force a fresh review after edits.

## What's coming next

A few advanced fields are saved by the studio but not yet consumed by the live-call runtime:

* **Per-tool runtime config** for `knowledge_lookup` and `web_search` (the tool's `config` block — knowledge-base IDs, restricted domains). Today these need to be configured at the campaign level via Settings → Tools, not per-stage.
* **Stage-level rail guards** — only the Global node's rail guards take effect. Put safety boundaries there.

Configure the rest at the right level for now; per-stage tool config will follow in a coming release.