State reference

​

What it gives you

​

CallState

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"})

state.save({"caller_phone": "+34 612 345 678"}, step="verify_phone")
state.plain("caller_phone")  # "+34612345678"
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, another save must wait for the caller
state.render("caller_phone")  # "none recorded yet."

"note" in state.name_set  # True

​

Every argument CallState takes

​

How a save works

1. state.save(values) checks the whole batch against the model first.
2. If one value is unknown, does not fit its type, or is longer than 64,000 characters, save raises StateRefused. Nothing from the batch is saved.
3. StateRefused.message is worded for the model, like caller_phone: expected a phone number with its country code. A task step shows it to the model, so the model can ask the caller again.
4. Otherwise every value is saved. Phone numbers, dates and the like are saved in their clean form.
5. Read state.values if you like, but never write to it. save is the one way in.

​

Confirmation

1. A value in confirm starts unconfirmed.
2. It becomes confirmed when its own step saves it with something in it.
3. Any other save of it makes it unconfirmed again. The caller must agree again.
4. state.withdraw("verify_phone") takes back every confirmation that step gave. The step runs again.
5. state.is_confirmed(name) is true when the value is filled and its confirmation stands.

​

How a value reads in a prompt

​

Filling a prompt

from unmute_core.model import render_prompt

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

1. Each {{name}} is found. Spaces inside the braces are fine: {{ name }}.
2. Each name is rendered with state.render. So a value that waits for confirmation reads none recorded yet.
3. A task step passes its own site, like task:verify_phone. A site is the place in the agent where a prompt is used: task:<name> for a task step, none for the main prompt. At its own site, the step sees the unconfirmed value.
4. The fill runs in one pass. A value that holds {{x}} is not filled again.
5. A saved value reaches the model whole. A native model call never cuts it.
6. A name the state does not hold raises MissingVariablesError. Its names list every missing name.

​

render_prompt

​

Which one to use

from unmute_core.livekit import ModelCallLLM, UnmuteAgent

agent = UnmuteAgent(AgentSpec(PROMPT, tasks=plan), state=state)  # the session's LLM answers
llm = ModelCallLLM(model, state=state)  # a ModelCall answers

from unmute_core.pipecat import ModelCallLLMService, UnmuteFlows

llm = ModelCallLLMService(model_call, state=state)  # a ModelCall answers
flows = UnmuteFlows(AgentSpec(PROMPT, tasks=plan), llm=llm, state=state, ...)

instructions = render_prompt(PROMPT, state)  # a native LLM of your own

​

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. required means the call cannot start without it. optional means it may be missing.
2. save_call_start(state, dispatched, *, env=True) reads state.call_start.
3. dispatched is the call_start object a call is dispatched with. UNMUTE_CALL_START gives the same for a local run, and the dispatch wins. Pass env=False to read only the dispatch.
4. With a mapping, only those names are taken. A missing required name raises CallStartError.
5. Without a mapping, any State value may be set and none is required.
6. Other names are dropped, and the log names them. A value that does not fit raises CallStartError, and nothing is saved.
7. The origin kind of these saves is call_start.
8. A name in call_start that the model does not have raises ValueError. So does a rule other than required or optional, and a name that is also in confirm. The caller is never asked for a value the call starts with.

​

How they read

1. An empty call-start value reads "" in a prompt. Other empty values read none recorded yet..
2. An optional call-start value never refuses a tool. A {{brand}} in an argument, a locked argument or an announce line reads as empty text.
3. The save tool (values_tool) leaves call-start values out. A call that names one is refused with brand is set when the call starts. It cannot change.
4. values_block shows each one as “set when the call starts”.

​

In a schema

{"name": "brand", "type": "str", "call_start": "optional"}

​

Values the call carries: state.call

state = CallState(State)
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)

1. session_id is new for each call and never changes. It is the same on every turn, task and handoff, on LiveKit and on Pipecat.
2. carrier_call_id is not session_id.
3. The library saves first_user_message from what the caller said first, and end_reason as the call ends.
4. A withheld or malformed number reads as None. It is never an error.

​

The three cases

1. Inbound phone call. The caller is calling_number. The agent’s own number is called_number. remote_number is the caller.
2. Outbound phone call. The agent’s own number is calling_number. The customer is called_number. remote_number is the customer.
3. Web call. channel is web. There are no numbers and no direction. The session_id is still set.

UNMUTE_CALL_START='{"call": {"direction": "inbound", "calling_number": "+34612345678"}}' uv run python agent.py

1. On a web call, every field you give applies.
2. On a phone call, the line wins. Its own channel, direction, calling_number, called_number and carrier_call_id stay. The dispatch fills only the empty ones.
3. agent_id and session_id always apply.

​

Where it reads

1. Python reads state.call.calling_number.
2. A prompt, a task text, a greeting, an announce line and a locked tool argument read {{call.calling_number}} and {{call.session_id}}.
3. An empty call value reads "" in a prompt.
4. A tool that locks an empty call value is refused: this tool reads call.carrier_call_id, which this call does not carry.
5. state.names, values_block, snapshot, save_values and state.dump() leave call out.

​

Read-only

... names 'call', which unmute-core reserves for what the call carries ...

​

Confirming the caller’s number

from unmute_core.prefetch import CallValue, Prefetch

class State(BaseModel):
    customer_phone: Phone | None = None

prefetch = Prefetch([CallValue("caller", "calling_number", ["customer_phone"])], state=State)
state = CallState(State, confirm={"customer_phone": "verify_phone"})

​

Saving values no task saves

from unmute_core.tools import values_block, values_tool

tool = values_tool(state, owners=plan_spec.owners())
values_block(state, owners=plan_spec.owners())

Values of this call. Save new ones with save_values.
- name (The caller's name): Ana
- party: 2
- booking, saved by the task book_table: none recorded yet.
- brand, set when the call starts: Salon Sol

1. values_tool builds the save_values tool. Each free value is an optional argument that may be null.
2. null puts a value back to its default.
3. owners maps a value to the task that saves it. Use TasksSpec.owners().
4. A value a task saves is refused with <name> is saved by the task <task>. Start that task to change it.
5. A call-start value is left out and refused too, with <name> is set when the call starts. It cannot change.
6. The tool returns {"ok": true, "saved": {...}}.
7. The tool saves the batch as a whole, like state.save. A value that does not fit refuses all of them.
8. If every value belongs to a task or to the call’s start, there is nothing to save. values_tool raises ValueError. free_values(state, owners) lists the values left to save, so you can check first.
9. AgentSpec(save_values=True), on either adapter, shows the block whenever State has values. It offers the save_values tool only when a value is free. With none free, the block’s first line names no tool.

​

values_tool

​

values_block

​

Turn it on

from livekit.agents import Agent

from unmute_core.livekit import filled_llm, function_tools
from unmute_core.tools import ToolRegistry, values_tool

registry = ToolRegistry([values_tool(state)])


class Desk(Agent):
    def __init__(self) -> None:
        super().__init__(instructions=PROMPT, tools=function_tools(registry, state))

    async def llm_node(self, chat_ctx, tools, model_settings):
        async for chunk in filled_llm(
            self, chat_ctx, tools, model_settings, state=state, save_values=True
        ):
            yield chunk

1. save_values=True on the spec gives that agent the tool. An agent the call is handed to has its own save_values. Each main-agent model request ends with the block as its last system message. A step’s request gets none.
2. save_values=True needs a state. Without one, UnmuteAgent and UnmuteFlows raise ValueError.
3. On a plain LiveKit agent, filled_llm runs the agent’s own LLM plugin. It fills the prompt from the state on each request. With save_values=True it ends the request with the block.
4. On a plain Pipecat pipeline, give tools_schema(registry, state) to the context. Then await fill_prompt(llm, worker, PROMPT, state, save_values=True) before the pipeline runs. It sends the filled prompt as the service’s system instruction, and sends it again after each save. See Pipecat.
5. is_values(role, text) from unmute_core.tools tells whether a message is that block. It is a system message that starts with the block’s header. Use it to drop the old block from a chat before you add a new one.

​

Building a State from type text

from unmute_core.state import CallState, StateSchema

schema = StateSchema(
    [
        {"name": "caller_phone", "type": "Phone | None", "confirm": "verify_phone"},
        {"name": "contacts", "type": "list[Contact]", "description": "People to call back."},
        {"name": "note"},
    ],
    [
        {
            "name": "Contact",
            "fields": [
                {"name": "name", "type": "str"},
                {"name": "email", "type": "EmailStr"},
            ],
        }
    ],
)
state = CallState(schema.model, confirm=schema.confirm, call_start=schema.call_start)

1. Every value starts empty. A list starts as []. Anything else starts as None.
2. Empty text counts as no value.
3. A Variable holds name, description, type (text by default), confirm and call_start.
4. A Shape is a named group of fields, like Contact. Name a shape in the type text.
5. A field of a shape is required unless its type ends in | None.
6. A bad row raises StateSchemaError or a Pydantic error. It names the row and the fix.

​

The type grammar

​

Value types

1. Phone drops spaces, dashes, dots and brackets. A leading 00 becomes +.
2. A phone number with no plus is saved only when one valid reading exists. The call’s country can help. Enter use_phone_region(...) with the country the call is in. Prefetch shows how.
3. A bad number is refused with a reason the model can act on. It may be too short, too long, or missing its country code.
4. NameEmail reads Jo Bloggs <jo@example.com> or a bare address. Paths read its parts: {{contact.email}}.
5. The format lets a tool schema or another reader name the type.
6. A bad Id is refused with the words: “expected an identifier: letters, digits, and then any of dot, dash, underscore or colon”. An Id has at most 64 characters. The refusal shows no pattern.
7. A number sent to a text value is saved as its text. NaN and infinity are refused there too.
8. A whole float reads as an integer in a prompt, a tool result, a webhook URL placeholder and CallState.snapshot(): 3.0 renders as 3. A locked argument that is a whole "{{price}}" still sends the float.
9. A choice (Literal[...]) is matched with the spaces around the answer and the choices ignored, so a padded answer still fits. The value saved is the choice as declared, " small" included.
10. Code says a BirthDate with its year and no weekday, like “June 5, 1979”, and a Spelled code a character at a time, in groups, like “K P, 4 8 2, 9 1 3”. A voice then reads each character on its own. Check a code’s pattern with your own validator.
11. A variable name may start with an underscore or be a model_* name. It works as any other name, in the prompt, in a tool’s arguments and in a task’s saves.

​

Listening 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)
state.save({"note": "call back"}, step="take_note")
stop()

1. A listener gets one StateEvent per save that changed something. A save that changed nothing sends nothing.
2. event.changes lists each value that changed. A change holds field, value as JSON, confirmed, and by.
3. confirmed is None for a value that never waits for the caller.
4. by is a StateOrigin. Its kind is one of nine: step, prefetch, call, call_start, tool, event, withdraw, start or reset. Any other kind raises a ValidationError when you build the origin.
5. listen(listener, replay=True) first sends the values already set, as one event of kind start.
6. A listener that raises is logged and removed. It never fails the save.

​

Who supplies a value

state.set_suppliers({"caller_phone": "verify_phone"})  # value name to task or group
state.clear_suppliers()  # an agent with no tasks has no suppliers

1. set_suppliers replaces the earlier map. It does not merge.
2. The adapters call it when a task plan runs. You call it only when you build your own task host.
3. Write to the map only through these two methods.

​

Troubleshooting

​

TypeError when you build the CallState

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

​

StateRefused from a save

​

MissingVariablesError when a prompt fills

​

ValueError from values_tool

​

Where to go next