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

> ## Agent Instructions
> Unmute compiles to exactly four targets. Pipecat and LiveKit are code targets: compile writes a Python project you run. SLNG is a hosted target: compile writes a deployment body and SLNG runs the agent, so it has no `unmute dev`. Twilio compiles to a small Python app that Twilio ConversationRelay calls; you host it, and it has no `unmute dev` either. Those four are the only values `provider` accepts in `targets.yaml`. Deepgram and ElevenLabs appear in these docs as model vendors, which is not the same thing as a target, and `slng` is both.
> The Go structs in `internal/spec` and `internal/ir` are the schema truth. Check a field against them, or run `unmute validate`, rather than against what you remember.

# Variables

> Declare a value once in state.py, fill it during the call, and read it only where it is needed.

A variable is a named value the call holds onto. You declare what it holds in
`state.py`, something fills it during the call, and the prompts that need it
name it.

On this page:

* [Quickstart](#quickstart) - declare, fill and read one value
* [Declare it](#1-declare-it) - the `State` class, and the `variables:` list
* [Fill it](#2-fill-it) - a task, a pre-fetch, or the call itself
* [Read it](#3-read-it-where-it-is-needed) - placeholders, and the greeting
* [The types you can declare](#the-types-you-can-declare) - Pydantic types, plus lists and your own models
* [Advanced](#advanced) - models, passing values to a tool, and seeding a value locally
* [Troubleshooting](#troubleshooting) - the four that come up most

## Keep only the values the call needs

**Keep state small.** Declare a variable when a value must survive a task or
handoff, feed a later tool, or supply a needed call fact to a prompt. Before
adding one used by only one prompt, check whether the agent needs the fact at
all. Prefer fewer values that each represent one useful fact or result; do not
split a timestamp into date and time just because both fields are available.

For a clock, replace `current_date`, `current_weekday`, and `current_time` with
`current_datetime` and `current_weekday`. The timestamp already carries the
date and time. Keep the weekday only if the prompt must name it; reading the
clock's answer avoids asking the model to calculate it. If nobody needs the
weekday, keep just the timestamp.

Merge these entries into an existing package:

```python state.py theme={null}
class State(BaseModel):
    current_datetime: str = ""
    current_weekday: str = ""
```

```yaml agent.yaml theme={null}
prefetch:
  - name: local_clock
    clock: now
    timezone: Europe/Madrid
    save:
      - current_datetime: result.datetime
      - current_weekday: result.day_of_week
```

Use a model for fields that travel together as a task result. Pre-fetch fills
plain values, so it cannot save the clock into a model. Keep separate values
when they have different confirmation steps or different readers.

## Quickstart

Declare a value, save it when a task finishes, and read it in a later prompt:

```python state.py theme={null}
from pydantic import BaseModel, Field


class State(BaseModel):
    requested_service: str = Field(
        "", description="The service the caller chose for this booking."
    )
```

```yaml agent.yaml theme={null}
agents:
  - name: concierge
    tasks:
      - name: choose_service
        when: Find out which service the caller wants.
        prompt: tasks/choose-service.md
        save:
          - requested_service: result.service
```

```markdown tasks/booking.md theme={null}
Requested service: {{state.requested_service}}
If no service is recorded, ask which service the caller wants.
```

```sh theme={null}
unmute validate my-agent
```

That is the whole loop: **declare, fill, read.** The rest of this page is each
step in full.

> [!NOTE]
>
> The snippets below extend an existing package. Merge them into the matching
> blocks in `state.py` and `agent.yaml`.

## 1. Declare it

Write a `State` class in `state.py`, next to `agent.yaml`. Each field is one
variable. Start with plain text:

```python state.py theme={null}
from pydantic import BaseModel, Field


class State(BaseModel):
    requested_service: str = Field(
        "", description="The service the caller chose for this booking."
    )
```

That is the whole declaration. `requested_service` is the name you will use
everywhere else, and `str` means it holds text. The default is what the value
starts as. Every field needs one: `= ""` for text, `= None` with `| None`, and
`= []` for a list.

`Field(description=...)` is what the model reads when a task asks it for this
value. Write it for the model, short, and so it reads whole when the value is
empty. The reasoning you want to keep for the next author goes in a `#` comment,
which reaches nothing.

`agent.yaml` lists a value under `variables:` only when it needs a `source:` or
a `confirm:`. It is a list, with one entry per value:

```yaml agent.yaml theme={null}
variables:
  - name: caller_name
    source: call_start
```

**name** `string` *required*

The field on `State` this entry configures. An entry naming no field is refused.

**source** `string`

Accepts `call_start`, `conversation` (SLNG only), or a [system call
fact](https://unmute.ai/reference/variables.md#sources). If omitted, the variable has no automatic call-fact
source; a task, pre-fetch, or session payload can still fill it. Route support is
checked for system sources. `conversation` requires a `Field(description=...)` and an
`= None` default in `state.py`. Inbound code-target calls require a default for
`call_start`.

**confirm** `string`

The name of the task that must hear the caller agree to a pre-fetched value. Until
confirmed, only that task can read it in a prompt and tools cannot silently use it. If
omitted, the value is usable as soon as it arrives.

A variable starts at its default. An unset value renders as `none recorded yet.`
in a prompt.

> [!NOTE]
>
> `unmute validate` and `unmute compile` read `state.py` by running it through
> `uv`, so `uv` must be on your `PATH` for a package that has one. The first run
> needs network. A package without a `state.py` needs no `uv`.

## 2. Fill it

Declaring a variable creates the box. Something still has to put a value in it.
There are three ways, and each has its own page:

| How | When it happens | Written where |
| - | - | - |
| A task's `save:` | when that task finishes | on the [task](https://unmute.ai/build/orchestration/tasks.md) |
| [`prefetch:`](https://unmute.ai/build/prefetch) | once, before the greeting | in a top-level `prefetch:` entry |
| `source:` | as the call starts | on the variable itself |

The common one is a task. Add `save:` to the task that learns the value:

```yaml agent.yaml theme={null}
agents:
  - name: concierge
    tasks:
      - name: choose_service
        when: Find out which service the caller wants.
        prompt: tasks/choose-service.md
        save:
          - requested_service: result.service
```

```markdown tasks/choose-service.md theme={null}
Find out which salon service the caller wants. Use what they have already
said and ask only if the service is missing or unclear. Then finish with
that service.
```

`save:` creates a finish argument named `service` from the
`requested_service` field. The field already owns the type and the description,
so the task does not repeat them.

A step must return every whole value it saves. Mark one it may leave out with
a `?` after the result field, as `- callback_time: result.callback_time?`.

All saved values are checked before any are saved. If one is invalid, the
task stays open so the model can correct its answer, and nothing changes.

## 3. Read it where it is needed

Saving a value does not put it in any prompt. A prompt reads a value only when
it names it, as `{{state.name}}`:

```markdown tasks/booking.md theme={null}
Requested service: {{state.requested_service}}
Use it if present. If no service is recorded, ask which service the caller wants.
```

An unset value renders as `none recorded yet.`, so write the sentence to read
whole either way. The instructions above work before and after the earlier task
saves the service.

A bare `{{requested_service}}` is refused, with the fix: `write {{state.requested_service}}`.

> [!WARNING]
>
> The agent that owns a task needs its own placeholder to remember the result
> after the task returns. It gets a completion status and its own earlier
> conversation back, not the private conversation inside the task.

### Use one in the greeting

The greeting renders once, before anyone speaks, so it can only name a value
that is already settled: one supplied at session start, a default, or a
prefetch save.

```python state.py theme={null}
class State(BaseModel):
    caller_name: str = "there"
```

```yaml agent.yaml theme={null}
variables:
  - name: caller_name
    source: call_start

conversation:
  greeting:
    speaks_first: agent
    say: "Hi {{state.caller_name}}, how can I help?"
```

> [!WARNING]
>
> Do not greet a caller by a name you have not checked with them. A name looked
> up from the number that called is a guess: people call from a partner's
> phone. Mark it with
> [`confirm:`](https://unmute.ai/build/prefetch#always-check-a-value-with-the-caller) and the
> greeting cannot use it until they say yes.

## The types you can declare

The type is what the call checks a value against before saving it. A task's
finish argument is built from it too, so the model is told what shape of answer
is wanted. `state.py` is ordinary Pydantic, so the types are Pydantic's.

| Type | What it holds |
| - | - |
| `str` | Free text, such as names and notes |
| `int` | A whole number |
| `float` | A number that may have a decimal part |
| `bool` | `true` or `false` |
| `date` | A calendar date, shown in a prompt as `2026-10-02` |
| `time` | A time of day, shown in a prompt as `16:30:00` |
| `EmailStr` | A valid email address, saved as plain text |
| `Annotated[str, StringConstraints(pattern=...)]` | Text that matches a pattern, such as an identifier |

Those cover most packages. The forms below are for when they do not.

### A phone number

`pydantic_extra_types.phone_numbers` has a `PhoneNumber`, which on its own saves
`tel:+34-600-111-222`. Wrap it so the saved value is E.164, `+34600111222`:

```python state.py theme={null}
from typing import Annotated

import phonenumbers
from pydantic_extra_types.phone_numbers import PhoneNumberValidator

Phone = Annotated[
    str | phonenumbers.PhoneNumber, PhoneNumberValidator(number_format="E164")
]


class State(BaseModel):
    caller_phone: Phone | None = None
```

Besides `phone_numbers`, two more `pydantic_extra_types` modules are open to
you: `currency_code` and `language_code`. Any other is refused. The
[reference](https://unmute.ai/reference/variables.md#what-a-field-can-be) lists the types in each.

### A fixed set of choices

```python state.py theme={null}
class State(BaseModel):
    booking_status: Literal["booked", "cancelled", "pending"] | None = None
```

Anything outside the set is refused where it enters, and the refusal lists what
was allowed. The default is `None`, because an empty string is not one of the
three words.

### A value that may be absent

`T | None` says `null` is a valid answer, not a failure. Use it when a lookup
can honestly come back with nothing.

### Several values of the same type

`list[T]` holds many. See [Keep several records](#keep-several-records) below.

> [!NOTE]
>
> LiveKit and Pipecat support every type on this page. On the SLNG target, a
> value a task saves, or one with `source: conversation`, can use most of them.
> [Tasks and flows](https://unmute.ai/targets/slng.md#tasks-and-flows) lists which. A
> value the dispatch fills stays plain `str`, because SLNG holds it as text. The
> [Twilio target](https://unmute.ai/targets/twilio.md) refuses a `state.py`.

The [reference](https://unmute.ai/reference/variables.md#the-state-class-holds-the-types)
has the full list, what is refused, and how a type is enforced. Your tools
still check business rules, such as whether a record exists and whether a slot
is free.

Every kind of type on this page appears once in
[`examples/customer-intake`](https://github.com/slng-ai/unmute/tree/main/examples/customer-intake),
one agent that collects a caller's details and hands them to a tool.

## Keep several records

Declare `list[T]` when later steps need several values of the same type. A list
starts as `[]`.

In a task's `save:`, `variable+:` appends one item and `variable:` replaces
the whole list:

```python state.py theme={null}
class State(BaseModel):
    notes: list[str] = []
```

```yaml agent.yaml theme={null}
save:
  - notes+: result.note
```

Appending skips `null` and skips an identical structured item. See
[saving rules](https://unmute.ai/reference/variables.md#saving-a-task-result-to-a-variable),
and [state design](https://unmute.ai/best-practices/state-design.md#choose-a-current-value-or-a-list)
to choose between a current value and a list.

## Advanced

Three things you will not need on your first agent.

### Group fields into a model

> [!NOTE]
>
> Skip this until you need it. A model is worth declaring when several fields
> always travel together and one tool fills all of them at once. Until then,
> separate variables are simpler to read and simpler to prompt.

A pre-fetch cannot fill a model or a list. Use a task to produce grouped fields;
use separate scalar variables for clock and lookup pre-fetch results. A single
pre-fetch may save several scalar variables from one result.

A model is a Pydantic class in `state.py`. Declare its fields, then use the
class as a field's type on `State`.

One model can be used by several fields. Each field holds its own value, and a
a task `save:` row saves all of the object's fields together.

For example, this package defines an object type called `Appointment` and
uses it for the variable `appointment`:

```python state.py theme={null}
from datetime import date, time
from typing import Literal

from pydantic import BaseModel, Field


class Appointment(BaseModel):
    booking_id: str
    service: Literal["haircut", "hair-color", "blowout"]
    date: date
    time: time


class State(BaseModel):
    appointment: Appointment | None = Field(
        None, description="The latest appointment successfully saved by the booking tool."
    )
```

Give a model field a `Field(description=...)` when it needs explaining to the
model. Its `description` is sent with the field in the finish argument.

> [!WARNING]
>
> Declare a field only when something in the package can fill it. A field no
> tool returns leaves the model inventing a value or sending an empty one, and
> it renders empty in every prompt that names it for the rest of the call.

#### Reading one field

`{{state.appointment}}` renders the whole object as compact JSON.
`{{state.appointment.date}}` reads one field, and a dotted path can follow nested
models. To read fields from a list item, save that item into its own variable
first.

For a name and an email address, use a two-field model such as
`Contact(name: str, email: EmailStr)`, so `{{state.contact.name}}` and
`{{state.contact.email}}` work. Pydantic's own `NameEmail` is one string, so a
prompt cannot read `.name` from it.

For deciding which fields belong together, separating a requested change from a
saved result, and choosing one record or a list, see
[Designing declared state](https://unmute.ai/best-practices/state-design.md#group-fields-that-describe-one-result).

### Hand a value to a tool

Sometimes the tool needs a value the model does not need to read or type. Use
`with:` for that argument:

```yaml tools/check_slots.yaml theme={null}
with:
  - service: "state.requested_service"
local:
  handler: tools/check_slots.py:check_slots
```

```python tools/check_slots.py theme={null}
def check_slots(date: str, service: str) -> Slots:
    ...
```

The model supplies `date`. The handler receives both `date` and the current
`service`. The handler's signature is the tool's input, so the model is asked
only for the arguments that `with:` does not name.

If the value is missing or unconfirmed, the tool stops before it runs. The
error names the task that supplies or confirms the value when one is declared,
and otherwise asks the model to collect it.

Injection is not the same as keeping a value private: tool results and spoken
messages can still contain it. See
[Reduce context sharing step by step](https://unmute.ai/best-practices/context-scope.md).

### Try it locally

```sh theme={null}
unmute dev my-agent --var caller_name=Priya
```

`--var` works for a declared variable with `source: call_start` or no `source:`
at all. Values are parsed against the field's type; pass JSON for a model or a
list, quoted for your shell. A value that does not fit its type stops the call
start, and the error names the field.

A system source such as `from_number` comes from the phone route instead, and
your machine is not one. To exercise prefetch and confirmation locally, stand
in for the network:

```sh theme={null}
unmute dev my-agent --source from_number=+15005550006
```

Which facts a route supplies, and in which direction, is in the
[source reference](https://unmute.ai/reference/variables.md#sources).

## Troubleshooting

### A prompt renders `none recorded yet.` on every call

The variable is unset. Either nothing has filled it yet, or the prompt that
reads it runs before the step that fills it.

**Fix:** check which step owns the `save:`, and write the sentence so it reads
whole either way. An unset value is normal early in a call, so the prompt should
say what to do about it:

```markdown theme={null}
Requested service: {{state.requested_service}}
If no service is recorded, ask which service the caller wants.
```

### The owning agent forgets a value after its task returns

A task returns a completion status and the owner (The agent that started a task. When the task ends, the caller goes back to it.)'s own earlier conversation. It
does not hand back the private conversation inside the task.

**Fix:** put a placeholder in the **owner's** prompt too. Saving is not sharing.

### A tool refuses to run, naming a value

The tool reads that value through `with:` or a webhook path, and the value is
empty or still unconfirmed.

**Fix:** the refusal names the task that supplies or confirms it. Run that step
first, or, when nothing supplies the value, have the model ask the caller.

### `--var` is refused for a variable

`--var` works only for a variable with `source: call_start` or no `source:` at
all. A system source such as `from_number` comes from the phone route, and your
machine is not one.

**Fix:** use `--source` instead, which stands in for the network:

```sh theme={null}
unmute dev my-agent --source from_number=+15005550006
```

## Where to go next

> [card] [Tasks](https://unmute.ai/build/orchestration/tasks.md)
>
> The usual way a variable gets filled: `save:` on the task that learns it.

> [card] [Pre-fetch](https://unmute.ai/build/prefetch.md)
>
> Fill a value before the greeting, and confirm the ones about the caller.

> [card] [Context scope](https://unmute.ai/best-practices/context-scope.md)
>
> Who can read what, and how to share less as the call goes on.

> [card] [Designing declared state](https://unmute.ai/best-practices/state-design.md)
>
> Which fields belong together, and when a list beats a current value.

> [card] [Credentials](https://unmute.ai/build/credentials.md)
>
> API keys and tokens, which are not variables.

> [card] [Variables reference](https://unmute.ai/reference/variables.md)
>
> Every type, field, source and assignment option.


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