Skip to content

Explore Seny

Simulations

Documentation

Simulations API

Simulations exercise an agent with a scripted caller so you can test behavior before (or instead of) a real conversation. Runs persist as normal conversations. Reading is gated on simulations.read; writing on simulations.write.

Scenario templates

Save a reusable customer-side goal for repeated runs.

GET    /api/v1/rest/simulation-scenarios
POST   /api/v1/rest/simulation-scenarios
{
  "name": "Asks for a manager",
  "prompt": "You are a caller who wants to escalate to a manager.",
  "acceptance_criteria": "Agent offers to transfer to a human."
}
GET    /api/v1/rest/simulation-scenarios/:id
PATCH  /api/v1/rest/simulation-scenarios/:id
DELETE /api/v1/rest/simulation-scenarios/:id

Runs

GET  /api/v1/rest/simulations              ?widget_id= &status=
POST /api/v1/rest/simulations
{
  "opponent_widget_id": "uuid",       // the agent under test
  "scenario_text": "Caller wants Saturday service hours.",
  "widget_id": "uuid",                // optional caller agent; omit for the built-in caller
  "tool_mode": "mock",                // mock | live | sandbox
  "surface": "web"                    // web | phone
}

Drive a turn-based run with POST /api/v1/rest/simulations/:id/step until it completes, then read the transcript with GET /api/v1/rest/simulations/:id.

Web-interaction test

POST /api/v1/rest/simulations/web

Runs the agent's widget on its real site in a headless browser, driven by a simulated visitor — synchronous, up to 5 minutes, recorded as a normal conversation.

Live writes are refused by default

POST /simulations/web, /simulations/phone and /simulations/campaign, and POST /simulations or /simulations/:id/rerun with tool_mode: "live", run the agent's real integrations, and an integration that is not in test mode writes real records even during a simulation. So these routes answer 409, with code: "live_writes_refused" and the integrations at fault, when the agent under test has a write-capable integration that is not mocked. They answer 503 (safety_check_failed) if its integrations cannot be read. mock and sandbox text runs are not checked.

For a deliberate live run, say so on that call:

{
  "allow_live_writes": true,
  "live_writes_reason": "Why this run may write, and whose permission it has"
}

The reason is required (10 to 500 characters) and is recorded in the audit log as simulation.live_writes_override, in your workspace and in the workspace that owns the agent. The create_simulation, rerun_simulation, run_web_simulation, run_phone_simulation and run_campaign_simulation MCP tools take the same two fields.

A campaign run checks the agent on every phone stage, because a move into a later stage can place a call. On another workspace's agent the refusal names no integrations, and the override answers 403 unless your workspace is its parent or you can run simulations there.

Manage a run

POST   /api/v1/rest/simulations/:id/cancel   # cancel an in-flight run
POST   /api/v1/rest/simulations/:id/rerun    # clone the config into a fresh run
DELETE /api/v1/rest/simulations/:id

These map to the create_simulation, step_simulation, run_web_simulation, and scenario MCP tools. Full schemas are in the OpenAPI reference.

Talk to Seny