> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scenarios

> Write the situations a simulated caller brings to your agent, and the criteria that decide whether your agent passed.

A scenario is a situation the simulated caller brings to your agent, and how you'll judge the agent. The **Scenarios** tab lists every scenario with its source, pass rate, and when it was last tested.

![Scenarios tab listing scenarios with their source badge, pass rate, last tested time, and a row actions menu](https://cdn.zeroruntime.ai/zrt/docs-resource/agent-builder/scenarios-tab.png)

## Default scenarios

Every account starts with four default scenarios. You can view and duplicate them, but not edit or delete them. Duplicate one to use it as a starting point.

| Scenario | What the caller wants |
| - | - |
| **Refund for a damaged order** | A refund for an order that arrived damaged. |
| **Asks for a human** | To speak to a real person instead of the agent. |
| **Off-topic question** | An answer about something unrelated to the business, such as the weather. |
| **Won't share required details** | Help with an account without giving the details needed to verify them. |

## Write a scenario

Select **Write a Scenario** in the page header, or **Add Scenario** in the scenario picker when you set up a simulation. Under **Creation method**, choose **Write a Scenario**.

![Add scenario panel with the Write a Scenario method selected and the scenario name, caller goal, and first line filled in, and Caller metadata turned on with a name key and value](https://cdn.zeroruntime.ai/zrt/docs-resource/agent-builder/write-scenario.png)

| Field | Required | What to enter |
| - | - | - |
| **Scenario name** | Yes | A short name, for example *Disputes an \$840 charge*. |
| **What does the caller want?** | Yes | The caller's goal, for example *dispute an \$840 charge they do not recognise*. The caller pursues this goal for the whole conversation. |
| **Caller's first line** | No | What the caller says first. Leave it empty and the caller opens in their own words. |
| **Caller metadata** | No | Key and value pairs the caller can use, such as `name: John Doe` or `order_id: 48213`. See [Caller metadata](#caller-metadata). |
| **Success criteria** | Yes | What the agent does when this goes right. Be specific and name the steps the agent must take. |
| **Failure criteria** | Yes | What the agent does when this goes wrong. Anything here fails the conversation, even if the goal is met. |

Select **Add scenario** to save it. Its source is **Manual**.

### Write good criteria

The judge scores your agent only against the scenario's criteria, so the criteria decide what a pass means.

* Name the observable steps: *"Agent asks for the order number, explains the refund timeline, and confirms the next step."*
* Put deal-breakers in the failure criteria: *"Agent shares account details before verifying the caller."*
* Keep each scenario to one situation. Split unrelated checks into separate scenarios so a failure points to one cause.

### Caller metadata

Turn on **Caller metadata** to give the caller made-up details, like a name, an account number, or an order ID. The caller can share these values when your agent asks for them.

Add a **Key** and a **Value** and select **+** for each entry. Keys can be up to 100 characters and values up to 1000.

## Generate scenarios from a prompt

Let Zero Runtime write realistic scenarios from your agent's instructions.

**1. Choose Generate from Prompt**

Select **Write a Scenario**, then choose **Generate from Prompt** under **Creation method**.

**2. Pick the agent and branch**

Choose the **Agent** and **Branch**. The **Prompt** field fills with that branch's committed system instructions. Select **Reset to main** to load the Main branch's instructions again.

**3. Edit the prompt (optional)**

Edit the prompt to steer the scenarios toward what you want to test. This only changes the input for generation. Your agent isn't changed.

**4. Choose how many**

Choose **3**, **5**, or **10** scenarios and select **Generate scenario**. Generation usually takes 10 to 20 seconds.

**5. Pick the ones to keep**

Expand a scenario to see its first line and criteria, and select the ones you want, or select **Select all**. Select **Add scenario** to save them, **Regenerate** for a new set, or **Edit Prompt** to go back.

![Generate from Prompt results showing three generated scenarios with their caller goals and checkboxes, the Select all link, and the Edit Prompt, Regenerate, and Add scenario buttons](https://cdn.zeroruntime.ai/zrt/docs-resource/agent-builder/generate-scenarios.png)

Generated scenarios have the source **Generated**. Edit them like any other scenario.

## Manage scenarios

Open a scenario's **⋮** menu:

* **View**: see the scenario's details, pass rate, and when it was last tested.
* **Edit**: change any field. Not available for default scenarios.
* **Duplicate**: make an editable copy.
* **Delete**: remove it from future simulations. Not available for default scenarios.

> [!NOTE]
>
> Edits and deletes apply only to future simulations. Every run keeps a copy of the scenarios it used, so past results stay as they are.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.