From 93b792e2f0e0bede23c7e5967e43cc5d7487551f Mon Sep 17 00:00:00 2001 From: Abhijai Srivastava Date: Tue, 14 Jul 2026 18:10:20 +0530 Subject: [PATCH 1/3] docs(simulation): Understanding Simulation (concept) --- .../concepts/understanding-simulation.mdx | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 src/pages/docs/simulation/concepts/understanding-simulation.mdx diff --git a/src/pages/docs/simulation/concepts/understanding-simulation.mdx b/src/pages/docs/simulation/concepts/understanding-simulation.mdx new file mode 100644 index 00000000..826185bd --- /dev/null +++ b/src/pages/docs/simulation/concepts/understanding-simulation.mdx @@ -0,0 +1,46 @@ +--- +title: "Understanding Simulation" +description: "How a simulation is assembled from three pieces, and where it fits" +--- + + +## What a simulation is + +A **simulation** runs your agent against simulated users so you catch its failures in a test instead of in production. The simulated user plays out a situation, your agent responds, and the whole conversation is scored, in voice or in chat. Run it before you ship, and again after every change, and you have a repeatable read on whether the agent is getting better or worse. + +## The three components + +Every simulation is assembled from three pieces. The [agent](/docs/simulation/concepts/agent-definitions) is who is tested, the [scenario](/docs/simulation/concepts/scenarios) is what happens, and the [persona](/docs/simulation/concepts/personas) is who is talking. A run brings the three together and executes them. + +who is tested"] --> RUN["Simulation run"] + S["Scenario
what happens"] --> RUN + P["Persona
who is talking"] --> RUN + style RUN fill:#2f2f2f,stroke:#ffffff,stroke-width:2px +`} /> + +Hold this shape and the rest of Simulation is detail: each of the three pieces has its own page, and everything else is how you run them and read what comes back. + +## One loop, walked once + +Take a support agent. You point Simulation at it, write a **refund request** scenario, and pick a **frustrated caller** persona. You run it, and a resolution eval fails: the agent quotes the wrong refund window. You shorten the prompt and add the policy, then run the same scenario and persona again. This time it passes, and you have proof the fix worked, not a hunch. + +## Where Simulation fits + +Simulation is the pre-production counterpart to [Observe](/docs/observe): Observe watches real traffic, Simulation rehearses it. It scores calls with the same templates as [Evaluation](/docs/evaluation), so a bar means the same thing in a test and in production. [Replay](/docs/simulation/concepts/replay) bridges the two by turning a real conversation into a scenario, and when a run exposes a weakness, [optimization](/docs/simulation/concepts/optimization) improves the agent automatically. + +## Keep exploring + + + + The agent under test, and how versions track changes + + + The test cases that decide what happens + + + The simulated customer your agent faces + + From afc2ba0c5abc92131071ca4fec5ef998ba0d06fc Mon Sep 17 00:00:00 2001 From: Abhijai Srivastava Date: Tue, 14 Jul 2026 19:10:24 +0530 Subject: [PATCH 2/3] docs(simulation): update Understanding Simulation Mermaid to consistent design --- .../docs/simulation/concepts/understanding-simulation.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/simulation/concepts/understanding-simulation.mdx b/src/pages/docs/simulation/concepts/understanding-simulation.mdx index 826185bd..2fdacff6 100644 --- a/src/pages/docs/simulation/concepts/understanding-simulation.mdx +++ b/src/pages/docs/simulation/concepts/understanding-simulation.mdx @@ -15,9 +15,9 @@ Every simulation is assembled from three pieces. The [agent](/docs/simulation/co who is tested"] --> RUN["Simulation run"] - S["Scenario
what happens"] --> RUN - P["Persona
who is talking"] --> RUN + A["Agent
The AI being tested"] --> RUN["Simulation"] + S["Scenario
The situation to test"] --> RUN + P["Persona
The user interacting with the AI"] --> RUN style RUN fill:#2f2f2f,stroke:#ffffff,stroke-width:2px `} /> From 1818a6789eb0affa0135f8865fb996f95c246c4e Mon Sep 17 00:00:00 2001 From: Abhijai Srivastava Date: Tue, 14 Jul 2026 21:00:40 +0530 Subject: [PATCH 3/3] docs(simulation): use the shared jigsaw diagram, no highlight Full jigsaw for the mental-model page, per the locked spec. Replaces the ad-hoc three-boxes-into-one Mermaid flowchart. --- .../concepts/understanding-simulation.mdx | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/src/pages/docs/simulation/concepts/understanding-simulation.mdx b/src/pages/docs/simulation/concepts/understanding-simulation.mdx index 2fdacff6..6d7d1958 100644 --- a/src/pages/docs/simulation/concepts/understanding-simulation.mdx +++ b/src/pages/docs/simulation/concepts/understanding-simulation.mdx @@ -12,14 +12,19 @@ A **simulation** runs your agent against simulated users so you catch its failur Every simulation is assembled from three pieces. The [agent](/docs/simulation/concepts/agent-definitions) is who is tested, the [scenario](/docs/simulation/concepts/scenarios) is what happens, and the [persona](/docs/simulation/concepts/personas) is who is talking. A run brings the three together and executes them. -The AI being tested"] --> RUN["Simulation"] - S["Scenario
The situation to test"] --> RUN - P["Persona
The user interacting with the AI"] --> RUN - style RUN fill:#2f2f2f,stroke:#ffffff,stroke-width:2px -`} /> +
+ + + + + Agent + who's tested + Scenario + what happens + Persona + who's talking + +
Hold this shape and the rest of Simulation is detail: each of the three pieces has its own page, and everything else is how you run them and read what comes back.