State

​

Define what the call remembers

from pydantic import BaseModel

from unmute_core.state import CallState, Phone


class State(BaseModel):
    caller_phone: Phone | None = None
    note: str | None = None


state = CallState(State, confirm={"caller_phone": "verify_phone"})

1. Every field needs a default, because every value starts the call empty. A field with no default raises TypeError.
2. confirm maps a value to the task step that must hear the caller agree to it.
3. Every call needs an agent id. Set UNMUTE_AGENT_ID, or pass call= with an agent_id. With neither, CallState raises SettingsError.

​

Save a value

from unmute_core.state import StateRefused

try:
    state.save({"caller_phone": "+34 612 345 678", "note": "call back"})
except StateRefused as refused:
    print(refused.message)  # worded for the model, so it can ask the caller again

1. save checks the whole batch first. One bad value refuses all of it, and nothing is saved.
2. A good value is saved in its clean form. The phone number above is saved as +34612345678.
3. save is the one way in. Read state.values or state.plain("note"), but never write to them.

​

Ask the caller to confirm a value

state.save({"caller_phone": "+34 612 345 678"}, step="verify_phone")
state.is_confirmed("caller_phone")  # True, the confirming step saved it

state.save({"caller_phone": "+34 612 345 679"})
state.is_confirmed("caller_phone")  # False, the caller must agree again
state.render("caller_phone")  # "none recorded yet."

1. A value in confirm is confirmed only when its own step saves it.
2. Any other save makes it unconfirmed again.
3. Until it is confirmed, prompts show none recorded yet., so the model never reads a misheard value back as fact. The confirming step still sees it, so it can read it back.

​

Filling a prompt

from unmute_core.model import render_prompt

prompt = render_prompt("Help the caller on {{caller_phone}}.", state)

1. {{name}} names a value. {{customer.status}} reads a path into a shape.
2. A name the state does not hold raises MissingVariablesError.
3. Call it again after a save, so the prompt shows the new values.

​

Values the call starts with

from unmute_core.call import save_call_start

state = CallState(State, call_start={"customer_id": "required", "brand": "optional"})
save_call_start(state, dispatched)
render_prompt("Welcome to {{brand}}.", state)  # "Welcome to Salon Sol." or "Welcome to ."

1. call_start names the values the dispatch sets. A required one must be there, or save_call_start raises CallStartError.
2. dispatched is the call_start object of the dispatch. For a local run, set UNMUTE_CALL_START to the same JSON.
3. The caller is never asked for these values, and the model cannot change them.

​

Values the call carries: state.call

state.call.session_id  # one id for the whole call
state.call.calling_number  # "+34612345678", or None
render_prompt("The caller is {{call.calling_number}}.", state)

​

Saving values no task saves

from unmute_core.agent import AgentSpec
from unmute_core.livekit import UnmuteAgent

spec = AgentSpec(PROMPT, tasks=plan, save_values=True)
agent = UnmuteAgent(spec, state=state)

from unmute_core.agent import AgentSpec
from unmute_core.pipecat import UnmuteFlows

spec = AgentSpec(PROMPT, tasks=plan, save_values=True)
flows = UnmuteFlows(spec, llm=llm, context=context, aggregators=aggregators, state=state)

1. Each request ends with a short block that lists every value and what it holds now.
2. The model saves with the save_values tool. null puts a value back to its default.
3. A value a task saves, or a call-start value, is refused with a reason the model can act on.

​

Listen to changes

def show(event) -> None:
    for change in event.changes:
        print(change.field, change.value, change.confirmed, change.by.kind)


stop = state.listen(show)

1. A listener gets one event per save that changed something.
2. listen(show, replay=True) first sends the values already set.
3. Call stop() to stop listening. A listener that raises is logged and removed.

​

Value types

​

Where to go next