> ## Documentation Index > Fetch the complete documentation index at: https://docs.plurai.ai/llms.txt > Use this file to discover all available pages before exploring further. # Ground in production traces > Base your mock environment, scenarios and evals on your agent's real production conversations. Grounding is where the simulation learns from your real production [traces](https://docs.plurai.ai/concepts.md#param-traces). It takes the simulation from realistic to **hyper-realistic**, by learning more than real behavior: * **Tool traffic:** how often each tool is called and what it returns, so your [digital twin](https://docs.plurai.ai/concepts.md#param-digital-twin) behaves like your real systems. * **Anomalies:** the odd responses, edge cases and noise your agent really meets. * **Speaking style**, for a conversational agent: how your users actually write, so simulated users ([personas](https://docs.plurai.ai/concepts.md#param-persona)) sound like them. * **Failures:** what goes wrong in production, so [evals](https://docs.plurai.ai/concepts.md#param-eval) target it and real failures become [scenarios](https://docs.plurai.ai/concepts.md#param-scenario). Grounding isn't required: Plurai works well zero-shot, from your agent's code alone, so you can skip this stage and add traces any time later. See [Grounding](https://docs.plurai.ai/concepts.md#param-grounding). [1 · Scan](https://docs.plurai.ai/guides/scan-your-agent.md) → [2 · Ground (optional)](https://docs.plurai.ai/guides/ground-in-production-traces.md) → [3 · Build the suite](https://docs.plurai.ai/guides/build-the-suite.md) → [4 · Run](https://docs.plurai.ai/guides/run-the-simulation.md) → [5 · Fix](https://docs.plurai.ai/guides/fix-and-keep-regressions.md) **Optional.** `/simulate` asks whether to connect traces, or run `/analyze-traces` on its own. Best done before you build the suite, so everything is generated grounded. ## What you get ![Production traces in the report](https://mintcdn.com/plurai/V3XeGRFO5iyJejs5/images/report/traces.png?fit=max\&auto=format\&n=V3XeGRFO5iyJejs5\&q=85\&s=29d9d4586b99c6b56de7e9db168229be) The Traces stage of the report, shown on a sample agent: how often production calls each tool, the failures customers hit, and which ones the Suite now replays. ## Choose your path | You have | Run | You get | | - | - | - | | Traces in LangSmith or Langfuse | `/analyze-traces` | A trace brief that grounds the mock environment, scenarios and evals. | | Conversation exports you want to continue | `/trace-to-scenarios` | Scenarios that resume each real conversation mid-flight. See [Replay production conversations](https://docs.plurai.ai/guides/replay-production-conversations.md). | | Exports in a format the plugin doesn't know | `/author-trace-adapter`, then `/trace-to-scenarios` | An adapter that teaches the converter your format. | | Real material and you're not sure which lane | `/ground-scenarios` | The plugin routes you. | ## Analyze production traces > [!NOTE] > > You don't have to run this on its own. `/simulate ` asks whether to connect a trace source as part of the full flow, and > grounds the suite if you do. Use the command below to run or re-run just this stage. ```bash theme={null} /analyze-traces ``` Or say it in chat: "Ground the simulation in our LangSmith traces." | Argument | What it does | | - | - | | `--source --project ` | Name the platform and project up front, so you aren't asked. | | `--no-trace-scenarios` | Don't turn trace failures into scenarios. | | `--max-new ` | The most trace failures to turn into scenarios. Defaults to 5. | | `--max-total ` | The most trace scenarios to keep on disk. Defaults to 10. | Trace analysis reads LangSmith and Langfuse directly. Arize spans can be replayed (see [Replay production conversations](https://docs.plurai.ai/guides/replay-production-conversations.md)), and every Run can be recorded to LangSmith, Langfuse, Arize or Braintrust. See [Observability platforms](https://docs.plurai.ai/integrations/trace-sources.md). You need the platform's client installed (`pip install langsmith` or `pip install langfuse`) and its credentials. The plugin reads them from the environment (`LANGSMITH_API_KEY`, or `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` with optional `LANGFUSE_HOST`) or asks for them. Credentials stay on your machine: they are never written under `plurai_sim/` and never uploaded. > [!NOTE] > > Trace export uses `LANGSMITH_API_KEY` (one underscore). Recording a run to LangSmith uses `LANGSMITH__API_KEY` (two underscores) in your agent's `.env`. See [Run the simulation](https://docs.plurai.ai/guides/run-the-simulation.md#record-it-in-your-observability-platform). **1. You say which traces matter** The plugin asks once for the platform, the project and, optionally, which conversations matter, such as "only failed runs", "only runs tagged X", or a list of conversation IDs. Narrowing is available on LangSmith; Langfuse takes the most recent traces. **2. Traces are exported locally, then uploaded** The SDK exports the traces on your machine into `plurai_sim/traces/` and uploads them as one archive. If this is your first upload, the plugin asks whether to anonymize first. **3. The backend writes the trace brief** The Plurai backend reads every trace and writes a brief covering your agent's capabilities, anomalies, how your users talk, the failures to evaluate, and scenarios worth testing. This takes from a few minutes to 40 or more. **4. You choose what to apply it to** Parts of the suite you haven't built yet are generated grounded. For parts that already exist (mock environment, scenarios, evals), you choose which to update. You get **Trace brief ready — grounded in N production traces**, a link to read the brief, and the brief itself in `plurai_sim/artifacts/trace_brief/`. Failures found in the traces become trace scenarios under `plurai_sim/trace_scenarios/`, each resuming the real conversation at the turn where it broke. They join the suite at the next `/simulation-generate-suite`. See [Replay production conversations](https://docs.plurai.ai/guides/replay-production-conversations.md). > [!TIP] > > Production traces hold real conversations, so we recommend turning on > [anonymization](https://docs.plurai.ai/security/data-and-privacy.md#anonymization-posture): personal data is scrubbed on your machine > before anything is uploaded. ## Continue real conversations ```bash theme={null} /trace-to-scenarios ``` `/trace-to-scenarios` turns conversation exports on disk into scenarios that **resume**: your agent starts with the real transcript and state already restored, and the simulated user continues from where the real one stopped. Use it for stalled threads, follow-ups after an escalation, and other moments you want to test exactly. * One export becomes one scenario. Pick a focused 10–30 conversations rather than hundreds. * Conversion runs locally in SDK code. No model reads the conversation. * It reads LangSmith thread exports from LangGraph agents (the default) and OpenInference span trees (`--source-format openinference`). For anything else, author an adapter first. * Your harness needs a `seed_state` that can restore a conversation. The plugin checks this and updates `simulate.py` if needed. * It works only with `anonymize: false`. Under an anonymized posture it refuses, with no fallback. Then run `/simulation-generate-suite` to generate the scenarios. ## Teach the converter a new format ```bash theme={null} /author-trace-adapter ``` Use this when your conversations are in a format the converter doesn't know: an in-house exporter's JSON, raw log lines, a benchmark episode, or a LangSmith export from an agent that isn't built on LangGraph. The plugin surveys the file's structure (not its content), writes a YAML mapping, and asks you to review it. The adapter is saved as `plurai_sim/plurai_adapters/.yaml`. Commit it like `plurai.config.yaml`; every later conversion reuses it with no model involved. Then pass the format name to `/trace-to-scenarios`. Nothing is uploaded at this step. Nested span exports other than OpenInference (for example Langfuse trace exports or OpenTelemetry GenAI spans) are refused by name. ## Not sure which lane ```bash theme={null} /ground-scenarios ``` `/ground-scenarios` asks what you have, **Conversations to continue**, **Records to start from**, **Both kinds of material** or **Unsure**, and routes you to `/trace-to-scenarios`, to `/upload-scenario-bundle` (see [Real records](https://docs.plurai.ai/guides/real-records.md)), or to both as one set. It never generates scenarios itself; run `/simulation-generate-suite` afterwards. ## What gets uploaded Each upload is one archive, sent over your connection to the Plurai backend after you approve the command. Your platform credentials are never uploaded. Every upload is recorded in `.plurai/uploads/audit.log` with its posture. For anonymization, retention and deletion, see [Data and privacy](https://docs.plurai.ai/security/data-and-privacy.md). ## Next steps > [card] [Build the suite](https://docs.plurai.ai/guides/build-the-suite.md) > > Generate the grounded mock environment, scenarios and evals. > [card] [Observability platforms](https://docs.plurai.ai/integrations/trace-sources.md) > > Connect LangSmith, Langfuse, Arize or Braintrust. > [card] [Real records](https://docs.plurai.ai/guides/real-records.md) > > Ground scenarios in real records and documents. > [card] [Data and privacy](https://docs.plurai.ai/security/data-and-privacy.md) > > What leaves your machine and how to anonymize it. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.