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

# Assistant simulations

> Test an assistant against an AI-played caller before it talks to a real one

Simulations let you check how an assistant behaves before a real caller does. Define a caller persona and a goal, and an LLM plays that caller against your assistant — either a fast text conversation or a real voice call — while a second LLM judges the result against the criteria you set.

## Where to find Simulations

Open an assistant, select the **Test** button in the header, and choose **Simulations**. The panel opens next to the editor, so you can adjust the prompt and rerun a test without leaving the page.

## Creating a test

Select **New test** and step through:

<Steps>
  <Step title="Start">
    Begin blank, or apply a persona [Milian](/assistants/milian-copilot) suggested — see **Generate with Milian** below.
  </Step>

  <Step title="Details">
    Name the test and write the caller's persona (identity and personality) in plain text.
  </Step>

  <Step title="Goal">
    Describe what the caller is trying to accomplish, for example: *"Your primary objective is to book a consultation for next week."*
  </Step>

  <Step title="Judge">
    Choose **Chat** or **Voice** mode, add the success criteria the judge should check, optionally list tools the assistant is expected to call, and set the maximum number of caller turns (up to 20, default 12).
  </Step>
</Steps>

<Tip>
  Select **Generate with Milian** instead of starting from a blank test. Milian proposes a batch of ready-made personas and success criteria for the assistant — review them and create the ones you want with one click.
</Tip>

## Chat vs. voice

* **Chat** — a fast, text-only conversation between the caller LLM and your assistant. No call is placed, and it's the cheaper way to iterate on a prompt.
* **Voice** — places a real call: a simulated caller with a synthesized voice talks to your assistant over the same path a live call takes, so the whole speech pipeline gets exercised. It takes longer than chat, costs more, and shows up in **History** like any other call; pick the caller's voice when you switch to this mode.

## Creating a test from a real call

Open a finished call in **History** and select **Create Simulation Test**. Famulor writes a persona, goal, and default success criteria (accurate information, professional tone, proper resolution or routing) from that call's transcript and analysis, saves them as a new test, and takes you to that assistant's Simulations panel — review and edit it there before the first run. It's the fastest way to turn a real conversation that went wrong into a regression test. See [Post-call analysis](/assistants/analysis#turn-a-real-call-into-a-simulation-test).

## Running tests and reading results

Run one test at a time, or select **Run all** to work through every test in order. Each run reports:

* a **pass or fail per success criterion**, with the judge's reasoning;
* the full **transcript**, labeled Caller / Assistant;
* **tool calls** made during the run, checked against anything you marked as an expected tool;
* for voice runs, a **latency breakdown** — end-to-end, time to first LLM token, time to first spoken audio, speech-recognition latency, and perceived response time — plus a **View call** link to the resulting call in History.

<Note>
  Simulations is text- or audio-based conversation testing, not a validator for your prompt's wording alone — the caller LLM can improvise within the persona and goal you set, so a test result reflects how the conversation actually unfolds.
</Note>

## Availability and cost

Simulations is a plan feature. If it isn't included, the panel says *Simulation testing is not in your plan* — compare plans under **Settings → Plan**.

Every workspace member can open the panel and read past runs; creating, editing, and running tests is limited to workspace owners and admins.

Simulations cost extra credits: every message in the run's transcript is charged at your workspace's **Call simulator message** rate — both in chat and in voice mode. Your current rate is listed on the **Usage** page under the credit rates (see [How usage is billed](/billing/minutes)), and each run appears there as a **Simulation run** transaction. Famulor checks your balance before a run starts and only charges for the messages actually produced. A voice run additionally consumes normal voice time for the call itself, since it exercises the full speech pipeline.

## API & MCP

| REST                                              | MCP tool                                        | Scope                                                    |
| ------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------- |
| `GET/POST /api/v1/assistants/{id}/tests`          | `list_assistant_tests`, `create_assistant_test` | `assistants:read` / `assistants:write`                   |
| `PATCH /api/v1/assistants/{id}/tests/{testId}`    | —                                               | `assistants:write`                                       |
| `DELETE /api/v1/assistants/{id}/tests/{testId}`   | `delete_assistant_test`                         | `assistants:write`                                       |
| `POST /api/v1/assistants/{id}/tests/{testId}/run` | `run_assistant_test`                            | `assistants:write` (voice mode also needs `calls:write`) |
| `POST /api/v1/assistants/{id}/tests/from-call`    | `create_assistant_test_from_call`               | `assistants:write`                                       |