Getting started

Sonora ships a single SDK for Node 18 and later. It covers agent registration, call import, suites, and alerts, and it installs the sonora CLI you will use for CI gates in step six.

npm install @sonora/sdk

Create an API key in the dashboard under Settings, then API keys. Keys are scoped to one project. Export it as SONORA_API_KEY and the SDK picks it up on init.

SONORA_API_KEY=sk_live_9f2ae51c04b7d803

import { Sonora } from "@sonora/sdk";

// reads SONORA_API_KEY from the environment
export const sonora = new Sonora();

Register the agent you want graded. The provider field tells Sonora how to tap the conversation: webrtc for browser agents, sip for phone lines, websocket for anything that streams audio or text frames.

const agent = await sonora.agents.register({
  name: "support-line-prod",
  provider: "sip", // "webrtc" | "sip" | "websocket"
});

console.log(agent.id); // agt_8f13ce, every call below takes it

If your stack produces audio or transcripts, Sonora can grade it. Native adapters ship for Vapi, Retell, LiveKit, Pipecat, and Twilio, so those connect with one config block. Everything else goes over the raw websocket transport.

Backfill history so your first scores land on real conversations, not synthetic ones. Transcripts import as JSONL, one call per line. Audio pulls from an S3 or GCS bucket, or you can upload files directly.

// transcripts: JSONL, one call per line
await sonora.calls.import({
  agent: agent.id,
  source: { type: "jsonl", path: "./exports/calls-2026-07.jsonl" },
});

// audio: point at a bucket ("s3" or "gcs"), or upload directly
await sonora.calls.import({
  agent: agent.id,
  source: { type: "s3", bucket: "acme-call-audio", prefix: "prod/2026/07/" },
  redact: { pii: true },
});

With redact.pii on, Sonora masks names, card numbers, and addresses in transcripts and mutes them in audio before anything is written to storage. Redaction runs inside the ingest worker, so raw payloads never persist.

A suite is a set of scenarios Sonora plays against your agent as a simulated caller. You describe the caller and what success looks like, the engine drives the conversation.

const suite = await sonora.suites.create({
  name: "core",
  scenarios: [
    {
      name: "reschedule-with-confirmation",
      persona: "caller wants to reschedule and gives a confirmation number",
      success: "appointment moved, new time read back to the caller",
      maxTurns: 12,
    },
  ],
});

const run = await sonora.suites.run(suite.id, {
  agent: agent.id,
  calls: 25, // simulated callers per scenario
});

console.log(run.url);

Run it from code or the CLI. Either way you get per-scenario scores in the terminal and a full trace in the dashboard.

$ sonora suites run core --agent support-line-prod

  reschedule-with-confirmation ....... 25 calls, avg 38s

  accuracy       93.2   pass
  tone           88.1   pass
  task success   71.4   fail   threshold 85

  1 of 1 scenario below threshold
  trace: app.sonoralabs.one/runs/run_02hx4

Every turn gets three scores from 0 to 100.

Accuracy

Does what the agent said check out against your knowledge base and the caller record. A wrong price, a wrong date, an invented policy: each one costs points on the turn where it happened.

Tone

Pacing, interruptions, dead air, and how the agent responds to frustration. Scored by models trained on annotated support calls, not keyword matching.

Task success

Did the caller get the thing they called for. Scored on the whole call, then attributed to the turn that won or lost it, so you see exactly where the reschedule fell apart.

Each suite sets a passing threshold per metric, 85 by default. A run fails when any metric average lands under its threshold, and the run page opens on the failing-turn trace: the transcript at that turn, the audio at that moment, and the grader notes explaining the deduction.

Suites catch the regressions you thought to test for. Alerts catch the ones you did not. This rule pings Slack when task success drops more than 3 points against its rolling 7-day baseline.

await sonora.alerts.create({
  name: "task-success-regression",
  channel: {
    type: "slack",
    webhook: process.env.SLACK_WEBHOOK_URL,
  },
  rule: {
    metric: "task_success",
    maxDrop: 3,     // points below baseline
    baseline: "7d", // rolling window
  },
});

For deploys, add a gate to CI. It runs the suite against the candidate build and exits non-zero when the average lands under your floor, so the pipeline stops before rollout.

sonora gate --suite core --min 90
# exit 0: suite average at 90 or above, deploy continues
# exit 1: below 90, deploy blocked, trace link printed