Scenarios

What is a Scenario?

A scenario defines a specific conversation that a persona can have. While the persona describes who the NPC is, the scenario describes what the conversation is about and how it should flow. Under the hood, each scenario is a finite state machine: a set of states connected by transitions with conditions evaluated by the AI.

Scenario Fields

• machine_key — A unique identifier for the scenario, used in API calls and multi-machine linking.
• name — Display name shown in the editor and to end users.
• description — A short summary of what this conversation covers.
• creator_objective — What the NPC is trying to accomplish or evaluate during the conversation. Included in AI context for transition decisions.
• creator_win_condition — The condition that defines a successful outcome for the scenario.
• creator_lose_condition — The condition that defines a failed outcome.

System Prompts

Each scenario has three system-level prompts that control AI behavior:

• chat_system_prompt — The base system prompt used during conversation. Combined with persona identity and state-level prompts.
• system_evaluation_prompt — Instructions for the AI when evaluating transitions and scoring after each turn.
• system_summarization_prompt — Instructions for generating conversation summaries, used for context compression in long conversations.

One Persona, Many Scenarios

A single persona can have multiple scenarios. A shopkeeper persona could power a "buying supplies" scenario, a "returning goods" scenario, and a "small talk" scenario, all sharing the same identity and voice.