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

# Live variables: values that follow the whole call

> Keep a value up to date after every caller turn in a flow agent: set live variables for the whole agent or one step, check them, and move the call when one matches.

A live variable is a value a flow agent keeps up to date for the whole call. After each thing the caller says, the agent reads the last few exchanges and saves any value the caller gave or changed, whichever step the call is in. This page shows how to set live variables up, check their values, and move the call when one matches.

Live variables are for [flow agents](https://docs.tryhamsa.com/agents/flow/overview.md). For the other ways a flow collects values, see [Extract values from the conversation](https://docs.tryhamsa.com/agents/variables/extracted-variables.md).

## When to use a live variable

| Use | When | Example |
| - | - | - |
| **Live variable** | The caller can say it at any point, or change it later | Their name, a new delivery date ("make it Tuesday"), asking for a person |
| **Variable on node exit** | One step is there to collect it, and the call shouldn't go on without it | The order number in a "Verify the order" step |

A variable on node exit is read once, when the call leaves its step, and it can be required. A live variable is read after every caller turn and can't be required.

## Set up live variables for the whole agent

**1. Open Live variables**

In the flow builder, click **Global settings** and open **Live variables** ("Extracted after every caller turn, in every node.").

**2. Add a variable**

Click **Add variable**. A new row opens straight away as "Variable N" until you name it.

**3. Fill in the card**

Give it a snake\_case name, a **Data type** (**String**, **Number**, **Boolean**, **Array (JSON)** or **Object (JSON)**) and an **Extraction prompt** that says what to listen for, for example "true when the caller asks to speak to a person, a human or an agent." For a string, you can limit the value to a list with **Use as enum**.

**4. Go back to the list**

Click **Back**. Each variable is a row; click a row to open its card again.

![Global settings, Live variables: four live variables, caller\_name, wants\_person, delivery\_date and an unnamed Variable 4 marked with a red dot, and the Add variable button](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/variables/live-variables-list-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=bd1ecc8128110711c2f803a625f7658a)

A red dot on a row means its card needs attention: the name is missing, already used, or taken by an environment key; the extraction prompt is empty; or a value check can never pass.

The extraction prompt can use other variables in `{{ }}`, and they are filled in before each reading. Relative dates the caller says ("tomorrow", "next Friday") are worked out from today's date in the agent's time zone.

## Turn live variables on or off in a step

Live variables run in Conversation steps and in the Start step (when it starts with a conversation). Other step types don't have caller turns, so they have none.

Open a Conversation step and go to **Variables**. The **Live variables** group ("after every caller turn") lists:

* every live variable from Global settings, marked **From Global settings**, with a switch. Switch one off and it isn't read while the call is in this step.
* the step's own live variables, marked **This node**. Click one to open its card, and **Back** to return.

![The Verify the order step's Variables: under Live variables, caller\_name and wants\_person From Global settings switched on, delivery\_date switched off, and order\_issue marked This node; under On node exit, order\_id and phone\_number](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/variables/step-live-variables-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=aec7c509fa42aae67713d9d544c75f86)

Switch a variable off in a step where the caller is likely to say something that looks like it but isn't, or where you don't need it and want one less thing for the agent to read.

To add a live variable for one step only, click **Add variable** and choose **Live variable**. It is read only while the call is in that step. It needs a name of its own: the editor marks a name that a live variable in Global settings or one of the step's variables on node exit already uses ("Variable name must be unique. This name is already used.").

## Check the value

Turn on **Check the value** in a live variable's card to keep only values that pass. "A value that fails isn't kept: the last one that passed stays."

For example, a `delivery_date` the caller can change at any time, which must be a date and not in the past:

| Field | Value |
| - | - |
| **Format** | **Date (YYYY-MM-DD)** |
| **Earliest** | `{{current_date}}` |

"To compare with another variable, write its name in \{\{ }}." The name is filled in when the value is checked, so `{{current_date}}` is today's date on the call. If the caller asks for a date that has passed, `delivery_date` keeps its last good value.

![The delivery\_date live variable's card: Required variable unavailable with its note, an extraction prompt, and Check the value switched on with Format Date (YYYY-MM-DD) and Earliest set to the current\_date variable](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/variables/live-variable-value-check-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=4b851ae99451a5190a91f89136c41d18)

Every check field is described in [Check the value](https://docs.tryhamsa.com/agents/variables/extracted-variables.md#check-the-value).

## Move the call when a live variable matches

Two kinds of rules read live variables:

| Rule | Where | What it does |
| - | - | - |
| **When a live variable matches** ("Rules on live variables") | A transition on a Conversation or Start step | Moves the call as soon as the rules hold, without the model choosing |
| **Offer it only when** | A **Prompt** transition's settings | Hides that path from the model until the rules hold. "They're checked again before each reply." |

**When a live variable matches** is offered once the agent has live variables ("Add live variables in Global settings first."), and its rules can only use live variables. See [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md#when-a-live-variable-matches).

### Example: the caller asks for a person at any step

**1. Add the live variable**

In **Global settings** > **Live variables**, add `wants_person`, **Data type** **Boolean**, with the extraction prompt "true when the caller asks to speak to a person, a human or an agent."

**2. Add the transition**

On each Conversation step where the caller may ask, click **Add** and choose **When a live variable matches**. Click the transition to open its settings and add the condition `wants_person` **Equals (=)** `True`.

![The settings of a When a live variable matches transition on the Verify the order step: one condition, wants\_person = True, with Add condition and Delete transition](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/variables/live-variable-transition-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=da588dabd4a593d363c0ac34ad6f61fb)

**3. Connect it**

Connect the transition to your Transfer call step.

On a call, the caller says "Can I just talk to someone?" in the middle of verifying their order. The live reading sets `wants_person` to `True`, the rule holds, and the call moves to the transfer. If the agent had started a reply in the old step, that reply is dropped, so only the next step answers.

Values are stored as text, so a Boolean reads `True` or `False`: compare with that exact text.

To offer a path to the model only after the caller has given their name, add a **Prompt** transition and, under **Offer it only when**, add `caller_name` **Exists (∃)**.

## Use live variables in prompts and messages

Write a live variable as `{{caller_name}}` anywhere a flow step takes variables. In the variables picker (type `{{`), they have their own section, **Live variables**, "Extracted after every caller turn." [Global steps](https://docs.tryhamsa.com/agents/flow/global-steps.md) can use them too.

When a live variable changes while the call is in a step, the agent uses the new value in its next reply.

## How it works on a call

* **After each caller turn**, the agent reads the last 3 exchanges with the caller, using the agent's own model, and saves the values the caller stated or confirmed. A value only the agent said doesn't count. This runs in the background, so it doesn't hold up the reply.
* **A newer turn wins.** If the caller speaks again before a reading finishes, the older reading is cancelled and the new turn is read.
* **The model sees the values.** With [Smart context manager](https://docs.tryhamsa.com/agents/flow/flow-settings.md#smart-context-manager) on, the model is shown the current value of every live variable on every turn, so it notices when the caller changes one.
* **Steps that use a value wait for it.** A step that uses a live variable (in its text, a rule, or a tool setting) waits up to 1.5 seconds for that turn's reading before it uses the value. After that it goes on with the values it has.
* **One extra model call per turn.** Each caller turn in a step with live variables adds one model call. A step with all of them switched off adds none.

## Good to know

* **A live variable can't be required.** "A required variable holds the conversation until it's extracted, and one demanded at every node would stall any call that never happens to mention it." If a step can't go on without a value, use a variable on node exit there.
* **A failed check keeps the last good value.** A value that fails **Check the value** is dropped; the variable keeps the last value that passed.
* **The latest write wins.** A live variable and a variable on node exit with the same name write to the same value; whichever was set last is what the call uses.
* **Don't make everything live.** Every live variable is read after every caller turn and adds to that reading. Keep the list to what can really come up anywhere, and collect step-specific values on node exit.

## Related

> [card] [Extract values from the conversation](https://docs.tryhamsa.com/agents/variables/extracted-variables.md)
>
> Variables on node exit, tool responses and keypad digits.

> [card] [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md)
>
> Every transition type, including live variable rules.

> [card] [Global settings](https://docs.tryhamsa.com/agents/flow/flow-settings.md)
>
> System prompt, smart context manager and live variables.

> [card] [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md)
>
> Conditions and loops on variable values.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.