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

# Variables

<p className="lead">
  Variables represent values stored in <code>conv.state</code> and are discovered automatically by scanning function code.
</p>

## How variables work

When you assign a value to `conv.state.customer_name` in code, `customer_name` becomes a tracked variable.

For example:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
conv.state.customer_name = "Alice"
```

The ADK discovers variables by scanning:

* global functions
* flow functions
* function steps

This means variables are not manually declared in a separate configuration file. They emerge from the code that uses them.

## Why variables matter

Use variables to carry state across turns and reuse values in prompts, topics, and templates.

<CardGroup>
  <Card title="Persist state">
    Store values that should survive across turns.
  </Card>

  <Card title="Drive prompts">
    Reference saved values in prompts and instructions.
  </Card>

  <Card title="Populate templates">
    Reuse state in SMS templates and other generated text.
  </Card>

  <Card title="Support logic">
    Let functions and flows branch based on previously stored values.
  </Card>
</CardGroup>

## Setting state in code

Set variables by writing to `conv.state`:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
conv.state.customer_name = "Alice"
conv.state.account_balance = 150.00
conv.state.is_verified = True
```

## Reading state in code

Read variables from `conv.state`:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
name = conv.state.customer_name  # returns None if not set
if conv.state.is_verified:
    ...
```

If a variable has not been set, reading it returns `None`.

## Using variables in prompts and templates

Variables can be referenced in prompts, topic actions, SMS templates, and related text fields using either of these forms:

* `{{vrbl:variable_name}}`
* `$variable_name`

Both forms are supported, but `{{vrbl:variable_name}}` is preferred because it is validated by the ADK.

### Example in prompt text

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
The customer's name is $customer_name and their balance is $account_balance.
```

### Example in a template

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
text: "Hi {{vrbl:customer_name}}, your booking is confirmed for {{vrbl:booking_date}}."
```

## Important rules

### In prompts

Use:

* `$variable`
* `{{vrbl:variable}}`

Do not use:

* `conv.state.variable`

### For structured values

Do not use:

* `$var.attribute`

If you need to expose a structured value in prompts, convert it to a string in Python first and store that string in state.

<Warning>
  **Prompt syntax is not Python syntax**

  In prompts and templates, use `$variable` or `{{vrbl:variable}}`, not `conv.state.variable`.
</Warning>

## Best practices

* variables are discovered automatically, so no manual registration is needed
* use descriptive snake\_case names
* initialize variables early, such as in `start_function` or near the beginning of a flow
* keep variable names consistent across functions and prompts
* prefer `{{vrbl:...}}` in user-facing text fields for better validation

## Related pages

<CardGroup>
  <Card title="Functions" href="/adk/reference/functions">
    Learn where variables are typically created, updated, and read.
  </Card>

  <Card title="SMS templates" href="/adk/reference/sms">
    See how state variables are used in reusable text messages.
  </Card>
</CardGroup>