Scenarios & Routing
In One Sentence
A scenario is a dedicated playbook that guides your agent through a specific customer journey — instructing it on what steps to follow, questions to ask, and actions to take when a particular intent is detected.
Why It Exists
Customer support covers diverse situations: handling order returns, checking shipment status, diagnosing technical issues, and processing cancellations. Rather than overloading your agent's general brand prompt with every possible workflow, scenarios break these journeys into modular, specialized playbooks that activate automatically based on customer intent.
What a Scenario Is (and Is Not)
| A Scenario Is | A Scenario Is Not |
|---|---|
| A structured playbook for a specific customer workflow | A library of static factual documents (that is a Knowledge Base) |
| Automatically triggered by intent matching during the conversation | A static script that must be manually selected by the user |
| A modular component configured on the agent draft | A separate standalone bot with its own deployment lifecycle |
Scenario Configuration Fields
When creating or editing a scenario in the Agent Builder, you configure three primary elements:
| Field | Limit | Purpose | Best Practices |
|---|---|---|---|
| Scenario Title | Max 100 chars | A concise name identifying the playbook | Use clear, recognizable labels (e.g., "Order Return Request", "Subscription Cancellation", "Delivery Status Lookup"). |
| Short Description | Max 300 chars | Summary explaining when this playbook applies | Describe the customer's goal or keywords (e.g., "Triggers when the customer wants to return an item, request a refund, or exchange a product"). |
| Scenario Prompt | Max 4,000 chars | Step-by-step guidance for handling the conversation | Outline required verification steps, questions to ask, API tool lookups to perform, and escalation criteria. |
The AI uses your Trigger Description to decide when to activate the playbook. Focus on describing customer intentions and typical phrasing rather than repeating the entire workflow policy.
How Intent Routing Works at Runtime
During a conversation, SupportOS dynamically routes customer turns through your active playbooks:
- Context Analysis: The routing engine evaluates the customer's latest message alongside earlier conversation turns and time context.
- Playbook Selection: If the request aligns with a scenario's trigger description, the engine activates that playbook.
- Additive Execution: The scenario instructions combine with your agent's rules, brand guidelines, and attached tools to deliver a precise response.
- Graceful Fallback: If no specialized scenario matches, the agent seamlessly handles the conversation using its baseline brand instructions and attached Knowledge Bases.
Best Practices for Writing Scenarios
- One Clear Intent per Scenario: Keep each playbook focused on a single customer goal (e.g., separate "Return Policy Inquiries" from "Process a Return").
- Structure Step-by-Step Checks: Number the steps in your prompt (e.g.,
1. Ask for order number,2. Run order lookup tool,3. Verify eligibility). - Define Escalation Conditions: Specify exact moments when the agent should offer human transfer (e.g., "If the order value exceeds $500, escalate to a supervisor").
- Reference Knowledge Bases for Facts: Let your attached Knowledge Bases handle detailed policy text while keeping scenario prompts focused on conversational flow and actions.
Next Steps
Explore Scenarios vs. Knowledge Bases to learn the decision framework for when to create a playbook versus uploading documents.