The State Graph
Lay a flow out as a graph — where the conversation is, what it decides, what happens along the way, and how it ends.
A long prompt asks the model to remember everything at once. The State Graph breaks a flow into pieces the platform can enforce: states the conversation moves through, checks graded against what was said, and actions that fire when a check passes.
The graph compiles into the same flow the rest of the platform runs — a campaign, an API call or an inbound number does not need to know a flow was drawn rather than written.
The Start node
Every graph begins at Start, and Start is the flow's master prompt: the instructions that apply for the whole conversation, whatever else is active. Edges out of Start are actions that run as the session begins.
Five kinds of node
The canvas toolbar groups nodes by what they do to the conversation:
| Family | Nodes | In short |
|---|---|---|
| Places | State, Collect Variable, Keypad Gather, Recording Consent | Where the conversation is — some hold it until a condition is met |
| Decisions | Evaluation, Evaluation Group, Change State | What was said, graded; and the moves that follow |
| Happens in passing | Say, Tool Call, System Message, Variable Update, Send Notification, and more | Actions that fire and let the conversation carry on |
| Ends the session | Transfer Call, End Session, Agent Handoff, Flow Handoff | The session leaves this flow |
| Wiring and notes | Event, Jump, Note, Scenario | Triggers, shortcuts and documentation |
How edges read
An edge means different things depending on what it connects, and this is the one idea worth learning before building anything:
- State → Evaluation is a visibility rule: grade that evaluation only while the state is active. It is not a step in a sequence.
- Evaluation branch → anything is that branch's reaction: what happens when the answer comes out that way.
- Start or State → Tool Call is an entry action: it fires when the session starts, or when the state activates.
Ungated evaluations cost a model call every turn
An evaluation with no state gating it is graded on every single turn. Gate each one on the state where its question actually makes sense.
In this section
- StatesNamed conditions a session is in — each with a typed value and an on/off flag — that steer the prompt and decide what the assistant may do.1 page inside
- Collecting informationNodes that hold the conversation on one question until the answer is valid — typed values, keypad entries and recording consent.
- DecisionsGrade the conversation with evaluations, answer several at once with a group, and apply named transitions with Change State.
- ActionsNodes that happen in passing — speak a line, run a tool, steer the assistant quietly, write memory, notify someone, start an automation.
- Handoffs and endingHand the session to a person, another agent or another flow — or end it cleanly, with a closing line that always completes.
- Events, jumps and notesReact to silence and time passing, keep a large graph readable, and document it for the next person who opens it.