Skip to main content
By default, the suite invents the records and documents its scenarios use. When realism matters, you can ground them in your own material: real records that scenarios start from, and real example documents that generated documents are modeled on. Run either after /simulation-scan-agent and before /simulation-generate-suite. Also see /ground-scenarios in Ground in production traces, which routes records and conversations for you.

​
Start scenarios from real records

Use this when a scenario’s starting point (the current page, the selected record, the active account) must refer to a real item in your agent’s data. For a large pool of records, a knowledge corpus can be a better fit.
1

You choose the records

The plugin confirms where your data is and asks how many scenarios you want and which slice of the data. A small, representative subset is recommended: 5–10 records that span the meaningful differences (type, value band, status). It then shows you the records it picked to confirm.
2

One folder per scenario

Each record gets a folder in plurai_sim/scenario_bundle/.
3

The bundle is uploaded

The SDK packs the folders into one archive and uploads it. If this is your first upload, the plugin asks whether to anonymize first.
The bundle layout:
Every folder needs ROLES.md and at least one record file. Values in agent_context.json take precedence over generated ones. Folder names can’t contain / or \. You get Scenario bundle ready with the set’s ID. Then run /simulation-generate-suite: each scenario is generated from one folder.
  • Records guide generation; they are not copied byte for byte. After the suite builds, the plugin checks that each scenario’s record ID exists in your real data and its fields match.
  • The bundle applies to the next suite build. A clone of your repo has the bundle’s ID but not the local setting that applies it, so its builds skip the bundle and say so.
  • A new upload always creates a new set. Rebuilding asks you to confirm before it deletes the old one.

​
Model documents on real examples

Use this whenever your scenarios involve a document your agent reads, produces or refers to: an invoice, form, ticket, report, statement, PDF or image. It isn’t only for document-extraction agents. The scan asks whether scenarios should include realistic documents; if you said yes, upload examples so they are modeled on real ones rather than generated from a description. Organize examples by family, one folder each:
The plugin asks for the folder’s path and confirms it. A family without FAMILY.md or without examples stops the upload, and nothing is sent. You get a summary such as “Doc example set ready … 3 families · 12 files stored”, and the next suite build uses them automatically.

​
Files and IDs

​
What gets uploaded

Only the records and documents you selected are uploaded, as one archive per upload, after you approve the command. Every upload is recorded in .plurai/uploads/audit.log. Uploaded sets stay until you delete them: ask in chat to “delete this set”. See Data and privacy.

​
Next steps

Build the suite

Generate scenarios from your records and documents.

Ground in production traces

Continue real conversations instead.

Knowledge base

Ground answers in a full corpus.

Data and privacy

Anonymization and retention.