States

A state is a named condition the conversation is in: identity_verified, booking, upsell. States turn one flow into a small state machine — several modes sharing one prompt and one set of tools, without building a separate flow for each.

Value and active

Every state has two independent things:

• a value, typed as Boolean, Number, String or Enum — optionally a list of them;
• an active flag, on or off.

Changing a value does not switch the state on or off. That separation is deliberate: a state can remember something (attempts = 2) whether or not it is currently steering the conversation.

A prompt state carries text instead of steering by value: while it is active, its text is added to the master prompt, so it shapes every turn rather than one moment.

A prompt state upsell adds "offer the annual plan if it comes up naturally" — but only while it is on.

Starting state

Exactly one top-level state can be marked Initially Activated. It is switched on before the first turn of every session, which is how a flow decides which mode it starts in. It does not change the state's value.

How a state changes

A state is switched on or off by:

• being initially activated;
• a Change State node, typically on an evaluation branch;
• the assistant, through the built-in functions for changing session state;
• auto-activate and auto-deactivate conditions on the state itself;
• a cascade from its parent — see Nested states.

Using states in the prompt

Prompt text can react to a state's value:

{{if session.state.identity_verified}}
You may discuss account details.
{{endif}}

The condition tests the value. To test whether the state is active instead, use the isActive keyword.

Gating by state

Tools, structured outputs and prompt modules can each be limited to particular states, so they exist for the model only when the state is active. A refund tool that appears only after identity_verified cannot be called before it.

On the canvas, an edge from a state to an evaluation does the same for grading: the evaluation is only asked while the state is active.

Peers

States that share a parent are peers — for a top-level state, every other top-level state. A state's activation pattern decides how it relates to its peers, for example whether it stays active globally while others come and go.