Why states matter
Organization and clarity
States provide a clear structure, making it easier to design, understand, and maintain agent flows.
Context management
States help overcome the limitations of limited memory capacity of language models, prevent hallucinations, and maintain the conversation’s accuracy.
Error handling
Breaking conversations into states allows for easily identifying errors and unexpected behavious in the agent’s conversation flow.
Improved accuracy
By focusing on one step at a time, states help language models stay on track, especially in longer conversations, and provide natural breakpoints for user confirmation.
State design principles
Focus on a single objective
Focus on a single objective
Each state should have a clear, singular purpose within the conversation flow.Example: Add a reschedule state (since user might ask to reschedule the call at any point of conversation) with 3-4 instructions instead of adding those 3-4 instructions in every state.
Meaningful instructions per state
Meaningful instructions per state
Aim for each state to contain a substantial set of instructions (ideally 6 or more, and up to 30). Avoid creating states with just 2-3 instructions; combine smaller steps into a single state.
Logical flow
Logical flow
States should flow logically from one to the next, guiding the user towards their goal in a natural, conversational way.
User-centric design
User-centric design
Design states with the user’s journey in mind. What information do they need at each step? What actions do they want to take?
Avoid over-segmentation
Avoid over-segmentation
Don’t break down the conversation into too many tiny states. Do not create states for specific tasks.Example: Do not create separate states for “low pay reason handling”, “payment delay handling”; rather create one state for “issue resolution”.Stick to one state for simple usecases and go upto 3-4 states for complex flows. Go beyond this only when dealing with very complicated flows or conversation with multiple reusable components.
Example: States in flight booking
Let’s revisit the flight booking example to see states in action:1
Greeting state
Agent welcomes the user and asks how it can help.
2
Discovery state
User indicates they want to book a flight. Agent presents flight options.
3
Booking state
Agent gathers passenger details (names, etc.) to confirm flight and seat choices.
4
Payment state
Agent securely processes payment information.
5
Confirmation state
Agent provides booking summary and offers further assistance.
Referencing states in agents
States can be referenced in the global insructions and state instructions by typing ’@’ and selecting the required state from the dropdown.
While you’ll select states using the ’@’ dropdown on the platform, throughout this documentation, states are referred to as
state:StateName.State transitions
State transitions define how the agent moves from one state to another during a conversation. These transitions are triggered by user input, variable values, or the completion of tasks within a state.How transitions work
Conditional logic
Transitions are based on conditions. For example, “If the user confirms the flight selection, then transition to
state:BookingState.”User input driven
What the user says or does determines the next state. For example, “If the user provides their name, then transition to
state:VerifyDetails.”Variable-based transitions
You can set transitions based on the value of variables. For instance, “If
variable:user_age is greater than 60, then transition to state:SeniorDiscount.”Example: Transition in flight booking
Example transition instruction:
Once the user has chosen a flight, update the variable selected_flight and then transition to state:booking_state1
From greeting to discovery
When the user says “I want to book a flight,” the agent transitions from the “Greeting State” to the “Discovery State.”
2
From discovery to booking
Once the user has chosen a flight, the agent updates the
selected_flight variable and then transitions to the “Booking State.”