> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telli.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Simulations
> Test an agent with simulated callers before real callers reach it
A simulation lets a simulated caller, the tester, talk to your agent. You describe the tester once. Then you run the simulation against a draft or a published version of the agent as often as you like. Checks look at every conversation of a run, so a prompt change that breaks a call shows up before a real caller hears it.
You find simulations in two places:
* **Simulations** in the sidebar lists every simulation of the account, with its runs on all agents.
* The **Simulations** tab of an agent lists the simulations added to that agent.
## Create a simulation
Open the agent and select the **Simulations** tab. Select **Add new Simulation** and describe what you want to test.
* Select **Continue with Charlie** to let [Charlie](/platform/charlie) write the simulation. Charlie reads the agent, works out the tester, the variables, and the tool answers, and asks about anything that is unclear.
* Select **Create Simulation manually** to fill in the form yourself.
| Field | What it sets |
| - | - |
| **Simulation name** | The name in the list, up to 80 characters. |
| **Describe the simulated caller** | Who calls, what they want, and how they behave. Write it as instructions to the tester. Use made-up personal data, because simulated calls are not deleted by data retention. |
| **Direction** | **Inbound** if the agent answers the call, **Outbound** if the agent places it. |
| **Who talks first** | **Agent** or **Tester**. If the agent talks first and the tester hears nothing for 10 seconds, the tester hangs up. |
| **Language** | The language the tester speaks. The agent keeps its own language settings. The default is the agent's language, or English for a multilingual agent. |
| **Tools** | What the agent's tools answer in this simulation. Tools you do not set use their default answer. |
| **Calendar tools** | Shown when the agent has a calendar. Sets the free slots and lets a booking fail. By default, the calendar is free at 09:00, 11:00, 14:00, and 16:00 on business days. |
| **Variables** | The contact the tester plays. Override [contact properties](/platform/contact-properties) to change what the agent knows about the caller. By default, the tester is Chris Keller with the email [mail@example.com](mailto:mail@example.com). To test an unknown caller, set the first name, the last name, and the email to **No value**. The tester does not see these values, so use the same name in the caller description. |
| **Max call length** | How long each conversation can last. Pick 5, 10, 15, or 30 minutes, or enter a number from 1 to 30. The default is 10 minutes. |
After you select **Create**, the **Add Checks** step lets you add [checks](#check-conversations-automatically) for the new simulation. Select **Done** to skip it.
To create a simulation from a real call, open the call in [Conversations](/platform/call-history) and select **Create simulation**. The button shows once the call is processed and the caller has said something. Charlie builds the simulation from the transcript, replaces personal data with made-up data, and adds the simulation to the call's agent.
To use a simulation of another agent, open the menu next to **Add new Simulation** and select **Add existing simulation**. Both agents then share the simulation, so an edit changes it for both. To change it for one agent only, use **Duplicate** in the simulation's menu, edit the copy, and select **Remove from agent** on the shared simulation.
## Run a simulation
Before you run, make sure the account has an active phone number that the agent can use. No call is dialed, but each simulated call takes that number as its own.
Select **Run** on a simulation. The Run dialog opens.
* **Version to test** is **Test draft**, **Test published version**, or a version under **Older versions**. The draft is selected when it has changes, otherwise the published version.
* **Amount of conversations** is how many conversations the run places. Pick 1, 2, 4, or 6, or enter a custom amount up to 20.
**Run all** starts one run for each simulation on the agent. Its dialog asks for the **Conversations per simulation** and shows the total. On the account-wide **Simulations** page, **Run** also asks for the **Agent**. If the simulation is not on that agent yet, **Add to this agent** adds it.
While a conversation is open next to the list, **Run** is in the simulation's menu.
While a run tests the draft, do not save changes to the draft. A save during the run makes its remaining conversations fail.
Each run shows its conversations under it. An account runs up to 5 simulated conversations at a time. The other conversations show **Waiting to start** until a slot is free.
## Review the results
Select a conversation to open it next to the list. A finished conversation shows the recording, the check results, and the **Overview** and **Transcription** tabs.
While a conversation is in progress, you see the live transcript. Select **Listen**, the headphones button, to hear the call.
When the checks are done, the icons show the result. A conversation icon is green when every check passed, red when a check failed, and orange when a check could not be run. A run icon is green when every conversation passed, red when the checks failed in every conversation, and orange when they failed or could not be run in some. Hover over an icon for the details. **Checks of this run** lists each check with how many conversations passed it.
From the menu of a run:
* **Run again** opens the Run dialog with the version and the amount of conversations of that run. The new run uses the simulation as it is now. For a run of the draft, it selects the current draft, or the published version if the draft has no changes.
* **Cancel run** hangs up the conversations in progress and skips the rest.
* **Delete** removes a run that has ended, with its conversations.
## Check conversations automatically
A check looks at every conversation of a run and marks it as passed or failed. Select **Checks** on the **Simulations** page, on an agent's **Simulations** tab, or in a simulation's menu. The dialog lists the checks for all agents and the checks for the agent or the simulation you opened it from. For other agents and simulations, it says where their checks are listed.
Select **Add Check**. **Applies to** sets which runs the check looks at. It starts with the place you opened **Checks** from, and you can change it.
* **All agents** applies to every simulation run in the account. If the tested agent version does not have the outcome or the tool that the check names, the run leaves the check out and shows a warning. On an agent's tab, such a check shows **Not checked here**.
* **One agent** applies to every run of that agent.
* **One simulation** applies to the runs of that simulation, on any agent.
| Type | Passes when |
| - | - |
| **Outcome** | A [call outcome](/deep-dives/call-analysis) has the value you expect. |
| **Appointment** | The agent books an appointment, at a specific time if you set one. |
| **Tool calls** | The agent makes the tool calls you list, in that order. Other tool calls can come in between. Each step checks the arguments you set. If **Result** is not **Any**, it also checks whether the call succeeded or failed. |
| **No tool call** | The agent never makes a certain tool call. |
A new, edited, or deleted check changes only runs that start after the change. Earlier runs keep their checks and results. Each result is **Passed**, **Failed**, or **Could not be checked**. A conversation shows **Not checked** when its run ended before the check, for example after **Cancel run**.
## How simulated calls work
* **No phone call.** The agent and the tester meet in a browser call, and no contact is created. The account still needs a phone number for the agent, as described in [Run a simulation](#run-a-simulation).
* **Tools.** Calendar tools, SMS, WhatsApp, call-me-later, and transfers are always simulated, so nothing is booked, sent, or transferred. Your own tools never run for real. Without a set answer, each call gets a new generated answer, so two calls of the same tool can disagree. Set an answer when the result matters. Ending the call, collecting data with its address validation, knowledge base search, and web search run as in a real call. Web search returns live results.
* **Length.** A conversation lasts at most as long as the simulation's **Max call length**, or less if the agent's or your plan's maximum call length is shorter.
* **Data.** Each conversation is recorded and transcribed, whatever the agent's recording settings or the tester's consent, and its outcomes and collected data are analyzed. Simulated calls do not show in [Conversations](/platform/call-history), and they send no webhooks, emails, CRM updates, or workflow triggers. [Data retention](/platform/data-retention) rules do not delete simulated calls.
* **Billing.** Simulated calls are billed like regular calls.
* **Time.** Conversations run on the current date and time.
* **Limits.** The tester cannot interrupt the agent in the middle of a sentence. A Duo agent that uses the browser cannot run simulations yet.
You can also ask [Charlie](/platform/charlie) to create, run, and review simulations and checks for you.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.