> ## 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.

# Simulation

> Test your agent against simulated callers before real users reach it, and see exactly where it fails.

Simulation tests your agent with realistic callers. A simulated caller brings a situation to your agent, talks to it in text or audio, and a judge scores your agent's side of the conversation against criteria you write. You see which conversations passed, which turn failed and why, and how to fix it.

Open **Simulation** in the sidebar. It has three tabs: **Runs**, **Scenarios**, and **Personas**.

![Simulation page with the Runs, Scenarios, and Personas tabs, the Run simulation and Write a Scenario buttons, and a list of runs with status, mode, pass rate, cost, and start time](https://cdn.zeroruntime.ai/zrt/docs-resource/agent-builder/runs-tab.png)

## Core concepts

| Concept | What it is |
| - | - |
| **Scenario** | A situation the caller brings to your agent, such as a refund request. It holds the caller's goal, an optional first line and caller details, and the **success** and **failure criteria** the judge scores against. |
| **Persona** | Who the caller is and how they behave, such as calm, angry, or confused, and the language they speak. A persona acts the same way in every scenario. |
| **Simulation** | A saved test setup: the agent and branch, the scenarios and personas, the mode, and the turn or call length limit. |
| **Run** | One execution of a simulation. Each run has a number (for example `Run #12`), a pass rate, and a cost. Re-run a simulation to get a new run. |
| **Conversation** | One scenario played by one persona against your agent, with its transcript, verdict, and cost. |
| **Judge** | The model that reads each finished conversation and decides whether your agent passed. It scores only your agent, never the simulated caller. |

## How a run is built

Every selected scenario is paired with every selected persona. In audio mode, each pair is also played once from every selected environment.

```
conversations = scenarios × personas            (text)
conversations = scenarios × personas × environments   (audio)
```

For example, 3 scenarios, 2 personas, and 2 environments make 12 audio conversations. A run can have up to 500 conversations.

## Modes

| Mode | What it tests | Limit per conversation |
| - | - | - |
| **Text only** | What the agent says: its prompt, LLM, tools, and knowledge base. Fastest and cheapest. | 5 to 30 turns (default 12) |
| **Audio** | A real voice call: speech recognition, the voice, turn-taking, and background noise. | 2 to 10 minutes (default 5) |

The modes you can pick depend on the agent's pipeline. Text only isn't available for an agent that uses a realtime model, because a realtime model has no separate text step. Run those agents in audio mode. See [Run a simulation](/agent-builder/simulation/run-a-simulation#choose-a-mode).

## Before you start

* **Deploy the branch you want to test.** A simulation tests the version that's deployed on a branch, not your draft. See [Deploy an agent](/agent-builder/deploy).
* **Have an active API key** on your account.
* **Have enough credits.** You see the estimated cost before anything runs.

## How it works

**1. Set up scenarios and personas**

Start with the default scenarios and personas, write your own, or generate scenarios from your agent's prompt. See [Scenarios](/agent-builder/simulation/scenarios) and [Personas](/agent-builder/simulation/personas).

**2. Run a simulation**

Pick the agent, branch, scenarios, personas, and mode, review the cost, and start the run. See [Run a simulation](/agent-builder/simulation/run-a-simulation).

**3. Review the results**

Follow the run live, open failed conversations to see the failing turn and the judge's reasoning, and copy its suggested fixes. See [Review results](/agent-builder/simulation/review-results).

**4. Fix and re-run**

Update the agent, [commit](/agent-builder/versioning/drafts-and-commits) and [deploy](/agent-builder/deploy) the change, then re-run the simulation to compare pass rates.

> **[Scenarios](/agent-builder/simulation/scenarios)**
>
> Write the situations and criteria to test.

> **[Personas](/agent-builder/simulation/personas)**
>
> Define who calls and how they behave.

> **[Run a simulation](/agent-builder/simulation/run-a-simulation)**
>
> Configure text or audio runs and see the cost.

> **[Review results](/agent-builder/simulation/review-results)**
>
> Find failing turns and how to fix them.


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