> ## 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.

# Environments

> Simulated health systems that your agent connects to during benchmarks.

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](/guides/simulators/overview) (FHIR EHRs, phone lines, fax endpoints, payer portals, web portals, clearinghouses, SFTP drops) and the datasets that populate them. [Benchmark runs](/guides/concepts/runs) instantiate the environment as a playground, the agent drives a rollout, and the [verification engine](/guides/concepts/verification) 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](/guides/concepts/sandboxes) instance with real endpoints your agent can connect to.

## Creating an Environment

```typescript theme={null}
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:

```bash theme={null}
# 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:

| Simulator         | Protocol        | Description                                                                          |
| ----------------- | --------------- | ------------------------------------------------------------------------------------ |
| **FHIR**          | REST (FHIR R4)  | Full EHR with patients, conditions, medications, encounters, and SMART on FHIR auth  |
| **Voice**         | WebSocket / SIP | Phone system with IVR menus, hold queues, and recorded call transcripts              |
| **HL7**           | HL7v2 over TCP  | Lab results (ORU), admissions (ADT), orders (ORM), and scheduling (SIU)              |
| **Fax**           | HTTP            | Inbound and outbound fax with document OCR and delivery tracking                     |
| **Payer**         | REST            | Insurance payer portal with prior auth submission, status checks, and patient lookup |
| **Clearinghouse** | REST            | Eligibility verification and claims status queries                                   |
| **CDS Hooks**     | REST            | Clinical decision support with hook registration, invocation, and feedback           |
| **Message**       | REST            | SMS/text messaging for appointment reminders and patient communication               |

## Environment Lifecycle

```mermaid theme={null}
graph LR
  C["Created"]:::state --> P["Playground"]:::state
  P --> A["Active (Running)"]:::state
  A --> T["Torn Down"]:::state

  classDef state fill:#2563eb,color:#fff,stroke:#1d4ed8
```

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:

```typescript theme={null}
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:

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Simulators" icon="server" href="/guides/simulators/overview">
    Learn about individual simulator types and their configuration.
  </Card>

  <Card title="Benchmarks" icon="list-check" href="/guides/concepts/benchmarks">
    Define tasks and criteria for your environments.
  </Card>
</CardGroup>