States

What is a State?

A state is a distinct phase in a conversation. When the NPC is in a particular state, it follows the behavior defined by that state's prompt instruction. The NPC is always in exactly one state at any point during a conversation. Rather than writing one massive prompt, you break the conversation into logical phases and write focused instructions for each one.

State Fields

• state_key — A unique identifier for the state within the scenario.
• label — Display name shown in the editor and diagram view.
• prompt_instruction — The system prompt that tells the AI how to behave in this state. Combined with the persona identity and scenario-level prompts on every turn.
• is_initial_state — Whether this is the entry point of the scenario.
• is_terminal_state — Whether reaching this state ends the conversation.
• display_order — Position in the editor list view. Drag to reorder; does not affect runtime behavior.

State Types

• Initial — The entry point. Every scenario requires exactly one initial state. All conversations start here.
• Intermediate — The default type. These are the core phases where the real conversation happens. Most states are intermediate.
• Terminal — An endpoint that concludes the conversation. A scenario requires at least one terminal state. You can have multiple for different outcomes (success, failure, timeout).

Follow-Up State

The follow-up state is a special virtual state managed automatically by the engine. You don't create it — it activates when the AI determines that the NPC needs to ask a clarifying question or probe further before making a decision.

You control when follow-up triggers by defining a follow_up condition in your state's evaluation criteria. For example: "The player gave a vague answer that doesn't clearly satisfy or violate the criteria."

When triggered, the NPC temporarily enters the follow-up state, asks a probing question, then re-evaluates the player's next response. If the follow-up resolves (the player gives a clear answer), the NPC exits back and applies the appropriate decision against the original state's transitions. Follow-up has its own redirect limit to prevent infinite loops.

Example

{
  "state_key": "greeting",
  "label": "Greeting",
  "prompt_instruction": "Introduce yourself as Captain Elara. Welcome the user to the trading post and ask what they need.",
  "is_initial_state": true,
  "is_terminal_state": false,
  "display_order": 0
}