States are conversation waypoints — not logical steps. Create one only when the agent must hear from the user before proceeding.

​
What Every State Must Cover

#QUESTIONWHAT TO WRITE
1PurposeWhat is this state trying to accomplish? (one sentence)
2Happy pathWhat does the flow look like when things go well?
3Edge casesWhat realistically goes wrong in this specific state?
4TransitionsWhen does the agent move to the next state?
5TerminationWhen and how does the call end from this state?

​
Basic State Format

## Purpose
[One sentence — what is this state for?]

## Steps
1. [First action]
   - If the user [condition 1 — be descriptive]:
     - [Action. Transition to state:X if needed.]
   - If the user [condition 2]:
     - [Action. Update disposition. Call end_interaction if needed.]
   - If the response is unclear:
     - Rephrase and ask once more. If still unclear: [fallback action].

## Guardrails
- [State-specific rules – retry limits, stop-and-wait, confirmations, etc.]

​
States Are Gates, Not Steps

Create a new state only when the conversation genuinely needs the user to speak before proceeding. Target: 2–3 states. Maximum: 3 for most use cases. Ask yourself: “Does the agent need to hear from the user before proceeding?” If yes, create a state. If no, keep it as a branching action within the current state.

​
Example

## Purpose
Confirm the customer's preferred callback time and date.

## Steps
1. Ask the customer when they prefer to be called back (date and time preference).
   - If the user provides a specific date and time:
     - Confirm the details back to them: "So I'll call you on Monday at 3 PM. Is that correct?"
     - Stop and wait for confirmation.
     - If confirmed: Set callback_time variable, transition to confirmation state.
     - If not confirmed: Ask for alternative time.
   - If the user is unclear or hesitates:
     - Offer standard options: "Would morning or afternoon work better?"
   - If the user refuses to schedule:
     - Accept gracefully, set disposition = refused_callback, end call.

## Guardrails
- Maximum 2 attempts to schedule. If still unclear, offer to end call or escalate.
- Do not assume a time if the user is vague. Always confirm.