> ## Documentation Index
> Fetch the complete documentation index at: https://arklex-06dfaf56-feat-arkdock-documentation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulations

> Run scenarios against a connected agent and record full conversation transcripts.

A simulation runs a set of scenarios against a connected agent and records the full conversation transcript for each run. Simulations are the execution layer — they produce the raw data that evaluations then score.

***

## Simulations list

Navigate to **Simulations** in the sidebar to see all simulations in your organization. The table shows:

| Column          | Description                                 |
| --------------- | ------------------------------------------- |
| Simulation Name | The name you gave the simulation            |
| Agent           | The agent it ran against                    |
| Scenario Groups | The groups the selected scenarios belong to |
| Created By      | The team member who created it              |
| Last Run        | When the simulation was created             |
| Status          | Current status (see below)                  |

### Status colors

| Status    | Color                                                                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Completed | <span style={{display:'inline-block', width:'12px', height:'12px', borderRadius:'3px', background:'#16a34a', marginRight:'6px'}} /> Green |
| Running   | <span style={{display:'inline-block', width:'12px', height:'12px', borderRadius:'3px', background:'#2563eb', marginRight:'6px'}} /> Blue  |
| Failed    | <span style={{display:'inline-block', width:'12px', height:'12px', borderRadius:'3px', background:'#dc2626', marginRight:'6px'}} /> Red   |

Use the **Filter** button to narrow results by agent, creator, or status. Use the **Search** bar to filter by simulation name or agent name.

***

## Creating a simulation

Click **New Simulation** to open the creation sheet.

### Prerequisites

Before creating a simulation you need:

* At least one connected agent (see [Agents](/agents))
* At least one scenario (see [Scenarios](/scenarios))

If no scenarios exist, the sheet will prompt you to go to the Scenarios page first.

### Simulation form

**Agent** — Select the agent to run the simulation against. If you have not connected any agents yet, an inline banner links to the Agents page.

**Name** — A descriptive name for this run (e.g. "Insurance Bot v3 - Home Deductibles - May 20").

**Description** — Optional notes about what this simulation is testing or what changed.

**Scenarios** — Select the scenarios to include. Scenarios are grouped by their scenario group in the selector. Use the search input and "Created by me" filter to narrow a long list. Click a scenario name to preview its goal, profile, and knowledge base before selecting.

**Conversations per scenario** — How many independent conversations Arkdock should generate for each selected scenario. Default is 1. The maximum per scenario is dynamic: the total conversation count across all selected scenarios is capped at 50, so the per-scenario limit decreases as you select more scenarios. Higher counts produce more variation and statistical reliability but take longer to run.

**Max turns per conversation** — The maximum number of exchange turns before a conversation ends. Default is 5. Maximum is 10. Set this to match the typical interaction length for your agent.

### Running the simulation

The **Run Simulation** button is disabled until an agent is selected, a name is entered, and at least one scenario is selected.

Click the button to start. You are navigated directly to the new simulation's detail page.

***

## Simulation detail page

### Header

* Simulation name and status badge
* Agent name, creation date, and conversation count

### Conversations table

Each row is one conversation generated during the simulation.

| Column   | Description                                      |
| -------- | ------------------------------------------------ |
| Scenario | The scenario ID that generated this conversation |
| Summary  | A short label derived from the scenario goal     |
| Goal     | The full goal text from the scenario             |
| Turns    | Number of exchange turns in the conversation     |
| Status   | Completed, Running, or Failed                    |

Click any row to open the **Conversation Modal** and read the full transcript.

### Conversation modal

Use the **Previous** and **Next** arrows to navigate between all conversations without closing the modal.

***

## Cancelling a simulation

Simulations that are queued but have not started yet can be cancelled. Click the kebab menu on a simulation row with **Pending** status and select **Cancel**. A toast confirms the cancellation.

Simulations that are already running cannot be cancelled mid-execution.

***

## Rerunning a simulation

Click the kebab menu on any simulation row and select **Rerun**. The rerun sheet pre-fills the simulation name and shows a summary of the original configuration (agent, scenario count). Edit the name if you want to distinguish this run from the original, then click **Run Simulation**.

The rerun creates a new simulation record with a new ID. It uses the same agent and the same set of scenarios but generates fresh conversations.

***

## Deleting a simulation

Click the kebab menu and select **Delete** and confirm. The simulation and its conversations are deleted. Evaluations that reference this simulation will note that the source simulation was removed.

***

## FAQ

<AccordionGroup>
  <Accordion title="How long does a simulation take to run?">
    Run time depends on the number of scenarios, conversations per scenario, max turns, and your agent's response latency. A simulation with 10 scenarios, 1 conversation each, and 5 turns typically completes in a few minutes.
  </Accordion>

  <Accordion title="What does a &#x22;Failed&#x22; conversation mean?">
    A conversation is marked Failed when Arkdock could not complete it — for example, if the agent endpoint returned an error, timed out, or produced an unparseable response. Failed conversations are excluded from evaluation scoring but remain visible in the transcript view.
  </Accordion>

  <Accordion title="Can I run multiple simulations against the same agent at the same time?">
    Yes. Simulations run independently and do not interfere with each other.
  </Accordion>

  <Accordion title="How is completion rate calculated?">
    Completion rate is the percentage of conversations that reached a `Completed` status. Conversations with a `Failed` status are counted as incomplete. Running conversations are excluded from the calculation until they finish.
  </Accordion>

  <Accordion title="Should I run a new simulation or rerun an existing one when I update my agent?">
    Create a new simulation after updating your agent. Rerun is best used to get more conversation samples from the same agent configuration. Running a fresh simulation preserves a clear record of which agent version was tested.
  </Accordion>
</AccordionGroup>