@verial-ai/sdk

TypeScript SDK and CLI for Verial, the healthcare agent simulation and testing platform.

Installation

npm install @verial-ai/sdk

Requirements

• Node.js 18+
• ESM only ("type": "module" in your package.json)

Quick Start

Create an environment, add a simulator, define a benchmark with evals, run it, and check results:

import { Verial } from "@verial-ai/sdk";

const verial = new Verial({ apiKey: process.env.VERIAL_API_KEY });

// 1. Create an environment (a simulated health system)
const env = await verial.environments.create({
  name: "Cardiology Clinic",
});

// 2. Add a FHIR simulator to the environment
const sim = await verial.simulators.create({
  type: "FHIR",
  name: "Primary EHR",
});
await verial.environments.addSimulator({
  environmentId: env.id,
  simulatorId: sim.id,
});

// 3. Create a benchmark with a task and eval
const benchmark = await verial.benchmarks.create({
  name: "Prior Auth Workflow",
  environmentId: env.id,
});

const task = await verial.tasks.create({
  benchmarkId: benchmark.id,
  name: "Submit prior auth for MRI",
  instruction: "Submit a prior authorization request for a brain MRI",
});

await verial.evals.create({
  taskId: task.id,
  label: "Prior auth submitted",
  assert: "A prior authorization request was successfully submitted for the MRI",
});

// 4. Run the benchmark
const run = await verial.runs.create({ benchmarkId: benchmark.id });

// 5. Check results
const result = await verial.runs.get({ id: run.id });
console.log(result.verdict, result.score);

Authentication

Get your API key from the Verial dashboard, then pass it to the client:

const verial = new Verial({ apiKey: "your-api-key" });

Or set it via the CLI:

verial auth set-key your-api-key

Common Use Cases

Run a benchmark

const run = await verial.runs.create({ benchmarkId: "bench_abc123" });
const result = await verial.runs.get({ id: run.id });

// Inspect individual task results
const { data: taskRuns } = await verial.taskRuns.list({ runId: run.id });
for (const tr of taskRuns) {
  const { data: evalRuns } = await verial.evalRuns.list({ taskRunId: tr.id });
  console.log(tr.name, evalRuns.map((e) => e.verdict));
}

Create a playground for manual testing

const playground = await verial.playgrounds.create({
  environmentId: "env_abc123",
});

// Access provisioned sandboxes (FHIR stores, voice lines, etc.)
const pg = await verial.playgrounds.get({ id: playground.id });
console.log(pg.sandboxes);

// Clean up when done
await verial.playgrounds.teardown({ id: playground.id });

Generate synthetic data

const dataset = await verial.datasets.create({ name: "Diabetic cohort" });
await verial.datasets.generate({
  id: dataset.id,
  prompt: "10 patients with Type 2 diabetes, ages 45-70",
});

Error Handling

All API errors throw VerialApiError with structured fields:

import { Verial, VerialApiError } from "@verial-ai/sdk";

try {
  await verial.environments.get({ id: "nonexistent" });
} catch (err) {
  if (err instanceof VerialApiError) {
    console.error(err.status);  // 404
    console.error(err.code);    // "NOT_FOUND"
    console.error(err.message); // "Environment not found"
  }
}

CLI

The package includes a CLI for managing resources from the terminal.

# Install globally
npm install -g @verial-ai/sdk

# Authenticate
verial auth set-key your-api-key

# Manage resources
verial environments list
verial benchmarks list
verial runs create --benchmark-id bench_abc123
verial runs get run_abc123
verial playgrounds create --environment-id env_abc123

Run verial --help or verial <command> --help for all available commands.

Configuration

| Option | Default | Description | | --------- | ------------------------ | ----------------- | | apiKey | (required) | Your Verial API key | | baseUrl | https://api.verial.ai | API base URL |

Documentation

For complete API reference and guides, visit docs.verial.ai.

Contributing: three-tier rebuild

The SDK is one link in a three-tier chain:

1. Handlers in apps/verial/api/src/** register OpenAPI metadata via per-resource openapi.ts files.
2. apps/verial/api/openapi.json is regenerated from those registrations.
3. apps/verial/packages/sdk/src/generated/ is regenerated from the spec via @hey-api/openapi-ts; resource facades in src/resources/ wrap those generated classes.

To add or change a public endpoint:

# 1. Edit the handler and its sibling openapi.ts
# 2. Rebuild the whole chain
cd apps/verial
npm run sdk:build

# 3. Review the diff to openapi.json and packages/sdk/src/generated/, commit it
# 4. If the change is breaking, add a major changeset
npm run changeset

CI runs npm run sdk:check on every PR and fails if openapi.json or src/generated/ would change when sdk:build is re-run, or if the spec breaks without a major changeset.

License

MIT