Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.verial.ai/llms.txt

Use this file to discover all available pages before exploring further.

An environment is a reusable definition of a simulated health system. In RL terms, it is the environment your agent acts inside during a rollout. It composes simulators (FHIR EHRs, phone lines, fax endpoints, payer portals, web portals, clearinghouses, SFTP drops) and the datasets that populate them. Benchmark runs instantiate the environment as a playground, the agent drives a rollout, and the verification engine scores the final sandbox state.

​
What Is an Environment?

Think of an environment as a virtual hospital or clinic. It links together all the simulated systems a healthcare AI agent might need:
  • An EHR with patient records (FHIR R4)
  • A phone system for scheduling and follow-ups (Voice/IVR)
  • A fax line for receiving and sending documents (Fax)
  • A payer portal for prior authorizations (Payer)
  • A clearinghouse for eligibility checks (Clearinghouse)
  • An HL7 interface for lab results and ADT messages (HL7v2)
  • Clinical decision support hooks (CDS Hooks)
  • Messaging endpoints for SMS/text (Message)
When you run a benchmark, Verial provisions each linked simulator as a live sandbox instance with real endpoints your agent can connect to.

​
Creating an Environment

const environment = await verial.environments.create({
  name: 'Regional Medical Center',
})
// → use environment.id as $ENVIRONMENT_ID in the curl examples below
At this point the environment is a container. You configure it by creating simulators and linking them: 
# 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 simulator
curl -X POST https://api.verial.ai/simulators \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "Payer", "name": "BlueCross Portal"}'
# → save the returned id as $PAYER_SIMULATOR_ID

# Link both simulators to the environment ($ENVIRONMENT_ID from above)
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/$PAYER_SIMULATOR_ID" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

​
Simulator Types

Environments can include any combination of the following simulator types:
SimulatorProtocolDescription
FHIRREST (FHIR R4)Full EHR with patients, conditions, medications, encounters, and SMART on FHIR auth
VoiceWebSocket / SIPPhone system with IVR menus, hold queues, and recorded call transcripts
HL7HL7v2 over TCPLab results (ORU), admissions (ADT), orders (ORM), and scheduling (SIU)
FaxHTTPInbound and outbound fax with document OCR and delivery tracking
PayerRESTInsurance payer portal with prior auth submission, status checks, and patient lookup
ClearinghouseRESTEligibility verification and claims status queries
CDS HooksRESTClinical decision support with hook registration, invocation, and feedback
MessageRESTSMS/text messaging for appointment reminders and patient communication

​
Environment Lifecycle

  1. Created. The environment definition exists with linked simulators. You can edit the configuration freely.
  2. Playground. When you create a playground from an environment, Verial provisions all linked simulators as sandboxes. Each sandbox gets a live endpoint (FHIR URL, phone number, fax number, etc.).
  3. Active. The playground is running and your agent can connect. All interactions are logged.
  4. Torn Down. The playground is stopped and all provisioned resources are released. Interaction logs are preserved for review.

​
Datasets

Datasets contain synthetic patient data that populates simulator sandboxes. You create datasets separately and link them to sandboxes after provisioning: 
const dataset = await verial.datasets.create({
  name: 'Primary Care Patients',
  data: {
    patients: [
      {
        name: 'John Smith',
        dob: '1965-03-15',
        gender: 'male',
        conditions: ['Type 2 Diabetes', 'Hypertension'],
        medications: ['Metformin 500mg', 'Lisinopril 10mg'],
        insurance: {
          plan: 'BlueCross PPO',
          member_id: 'BCB123456789',
        },
      },
    ],
  },
})

​
Reusability

Environments are designed to be reused across multiple benchmarks. Create one environment that models your target health system, then reference it from different benchmarks: 
const env = await verial.environments.create({ name: 'Cardiology Practice' })
// ... link simulators ...

const priorAuthBenchmark = await verial.benchmarks.create({
  name: 'Prior Auth Flow',
  environmentId: env.id,
})

const schedulingBenchmark = await verial.benchmarks.create({
  name: 'Appointment Scheduling',
  environmentId: env.id,
})

​
Next Steps

Simulators

Learn about individual simulator types and their configuration.

Benchmarks

Define tasks and criteria for your environments.