Simulators

​

Protocol matrix

​

Lifecycle

1. Create the simulator once, configure it (e.g. portal flavor, IVR flow, determination rules).
2. Link it to one or more environments. Environments compose simulators plus datasets.
3. Provision a sandbox when a playground is created or a benchmark run starts. The sandbox gets its own credentials, isolated state, and evidence stream.
4. Drive the sandbox from your agent using the /v1/benchmark-runs/{id}/ endpoints (or the direct sandbox endpoints during authoring).
5. Tear down at the end of the run. The sandbox stops accepting traffic, but all recorded interactions remain for review and verification.

​

Creating and linking

# Create the FHIR simulator
curl -X POST https://api.verial.ai/simulators \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "Fhir", "name": "Primary EHR"}'
# → save the returned id as $FHIR_SIMULATOR_ID

# Create the payer portal simulator
curl -X POST https://api.verial.ai/simulators \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Payer",
    "name": "RadMD Sandbox",
    "config": {
      "portal": "radmd",
      "default_determination": { "status": "approved" }
    }
  }'
# → save the returned id as $PORTAL_SIMULATOR_ID

# Create the environment (environments are also available via the SDK as verial.environments.create)
curl -X POST https://api.verial.ai/environments \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Regional Medical Center"}'
# → save the returned id as $ENVIRONMENT_ID

# Link the simulators to the environment
curl -X POST "https://api.verial.ai/environments/$ENVIRONMENT_ID/simulators/$FHIR_SIMULATOR_ID" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

curl -X POST "https://api.verial.ai/environments/$ENVIRONMENT_ID/simulators/$PORTAL_SIMULATOR_ID" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

​

Provisioning

• Allocate resources. FHIR stores are created in GCP Healthcare, phone numbers are leased from the voice pool, SFTP drops are initialized, portal logins are minted, CDS Hooks endpoints are registered.
• Load datasets. Any datasets linked to the simulator are seeded into the fresh sandbox (patients into FHIR, files into SFTP, determination rules into the portal).
• Return credentials. The benchmark-run response includes a endpoints map (for path-routed simulators) and, where applicable, each sandbox’s credentials payload (phone numbers, portal URLs, usernames, fax numbers).
• Record interactions. Every request to the sandbox is captured as evidence. Voice calls produce transcripts, fax submissions produce OCR’d documents, portal submissions produce UI events.
• Tear down. After the last task run completes, sandboxes release their resources. Interaction evidence persists so criteria can score the rollout.

​

Configuration vs runtime credentials

• Configuration is set at POST /simulators time (and editable via PATCH /simulators/{id} until provisioning). It describes the shape of the simulated system: which payer portal to render, which IVR menus to expose, which determination rules to apply, which CDS cards to return.
• Runtime credentials are generated when the sandbox is provisioned. They are unique per sandbox, scoped to that sandbox’s lifetime, and include things like a FHIR base URL, a leased phone number, a portal username and password, a fax number, or an SFTP root path. The agent reads them out of the benchmark-run response or the sandbox’s credentials payload.

​

Next Steps