@voicelayer/sdk

Build voice AI agents that run real business processes — in one file.

# The SDK is lean. Providers (STT / TTS / LLM / VAD / turn detection) install
# separately, so you only pull in the vendors you actually use. These four are
# the default pipeline:
pnpm add @voicelayer/sdk \
  @voicelayer/agents-plugin-deepgram \
  @voicelayer/agents-plugin-openai \
  @voicelayer/agents-plugin-silero \
  @voicelayer/agents-plugin-livekit

See Providers for the full list. Use a provider you haven't installed and the SDK throws a single, actionable error telling you what to add.

Hello, voice agent (30 seconds)

// agent.ts
import { defineAgent } from '@voicelayer/sdk';

export default await defineAgent({
  name: 'hello',
  prompt: 'You are a friendly receptionist. Ask the caller how you can help.',
}).start(import.meta.url);

node --import tsx agent.ts dev

Call your LiveKit number. The agent answers. That's it. STT, LLM, TTS, VAD, turn detection — defaults are picked for you. Swap them later with one config line.

A real agent (FNOL in 100 lines)

The voice plumbing isn't the hard part. The hard part is running a business process to completion: collecting required fields, validating them, escalating on legal threats, persisting memory across calls, handing off to a human, and writing the result back to your CRM.

That's what this SDK does. One declaration:

import { defineAgent, defineProcess } from '@voicelayer/sdk';

// A connector is any object with this shape — write one for whatever system
// you already use. Its methods land on `ctx.connectors.<name>`.
const crm = {
  __connector: true as const,
  name: 'crm',
  api: {
    createClaim: async (data: Record<string, unknown>) => {
      const res = await fetch('https://your-crm.example.com/claims', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(data),
      });
      return (await res.json()) as { id: string };
    },
  },
};

export default await defineAgent({
  name: 'fnol',
  prompt: 'You are a calm First Notice of Loss intake agent.',

  // 1. The business process. Declarative — the SDK extracts fields from
  //    each utterance, validates them, and decides when the call can end.
  process: defineProcess({
    collect: {
      incidentDate:     { type: 'datetime', required: true },
      vehiclesInvolved: { type: 'string[]', required: true, min: 1 },
      injuries:         { type: 'boolean',  required: true },
      policeReport:     { type: 'boolean' },
      claimNumber:      { type: 'string',   required: true, pattern: /^[A-Z]{2}-\d{8}$/ },
    },
    completeWhen: 'all-required-captured',
    onComplete: async (data, ctx) => {
      const claim = await ctx.connectors.crm.createClaim(data);
      await ctx.say(`Your claim number is ${claim.id}. You will receive a text shortly.`);
    },
  }),

  // 2. Triggers — fire deterministically before the LLM sees the turn.
  triggers: {
    legalThreat:  { on: /\b(attorney|lawyer|sue|lawsuit)\b/i, then: 'handoff' },
    severeInjury: { on: 'signal:medical_emergency',          then: 'handoff' },
  },

  // 3. Handoff — real SIP transfer, with state briefing for the human agent.
  handoff: {
    fallback: '+15555550100',
    briefing: ({ data, transcript }) =>
      `Caller reported FNOL. Captured: ${JSON.stringify(data)}. Last 3 turns: ${transcript.tail(3)}`,
  },

  // 4. Memory — persisted across calls, scoped to the caller. PII auto-redacted.
  memory: {
    scope: 'caller',
    retentionDays: 90,
    piiFields: ['ssn', 'dob'],
  },

  // 5. Connectors — available on ctx, and as LLM tools when `expose: true`.
  connectors: { crm },

  // 6. Compliance — opt-in posture, defaults are safe.
  compliance: ['tcpa'],
}).start(import.meta.url);

That's a complete production FNOL agent. 60 lines of config, no boilerplate. Same file runs in dev and prod. Same file is what LiveKit forks for each call.

Mental model

You declare one Agent. The Agent has six knobs:

| Knob | What it does | |---------------|--------------------------------------------------------------------| | prompt | What the LLM says when nothing else fires. | | process | The structured outcome the call exists to produce. | | triggers | Deterministic routes that run before the LLM (regex, signals). | | handoff | How to transfer to a human, with what context. | | memory | What persists across calls, scoped, with PII rules. | | connectors | Typed external systems the agent can read/write. |

Everything else (STT, TTS, LLM, VAD, turn detection, transcript persistence, security guards, telemetry) is on by default with sane choices, and swappable in one line when you need to.

Three tiers of customization

Tier 1 — Config only. Covers ~80% of voice agents. The example above is Tier 1.

Tier 2 — Hooks. When config isn't enough, drop into hooks. Same agent, same file:

defineAgent({
  // ...
  async onUtterance(text, ctx) {
    if (text.includes('refund')) ctx.metadata.flagged = true;
  },
  async onFieldCaptured(field, value, ctx) {
    if (field === 'claimNumber') await ctx.connectors.crm.lookup(value);
  },
  async onCallEnd(outcome, ctx) {
    await fetch('https://your-api.example.com/call-ended', {
      method: 'POST',
      body: JSON.stringify({ callId: ctx.call.id, reason: outcome.reason }),
    });
  },
});

Tier 3 — Full control. When hooks aren't enough, take the wheel:

defineAgent({
  // ...
  async onCall(ctx) {
    // You own the entire conversation loop.
    await ctx.say('Hi! What is your policy number?');
    const policy = await ctx.ask();
    const account = await ctx.connectors.crm.lookupPolicy(policy);
    // ... do whatever ...
  },
});

You never have to leave the SDK. You never import a primitive.

Swapping models

Each provider is a small factory you import from the SDK. Pick the pieces you want; the SDK wires them into the pipeline:

import { defineAgent, deepgram, openai, cartesia } from '@voicelayer/sdk';

defineAgent({
  // ...
  models: {
    stt: deepgram.stt({ model: 'nova-3' }),
    llm: openai.llm({ model: 'gpt-4o' }),
    tts: cartesia.tts({ voice: 'sonic-english' }), // pnpm add @voicelayer/agents-plugin-cartesia
  },
});

Provider plugins load lazily — the vendor SDK (and its native binaries) only loads on first use, never at import time.

Providers

Install only what you use:

| Provider | Package | Factory | |----------|---------|---------| | Deepgram (STT, TTS) | @voicelayer/agents-plugin-deepgram | deepgram.stt(), deepgram.tts() | | OpenAI (LLM, TTS, Realtime) | @voicelayer/agents-plugin-openai | openai.llm(), openai.tts(), openai.realtime() | | Cartesia (TTS, STT) | @voicelayer/agents-plugin-cartesia | cartesia.tts(), cartesia.stt() | | ElevenLabs (TTS) | @voicelayer/agents-plugin-elevenlabs | elevenlabs.tts() | | AssemblyAI (STT) | @voicelayer/agents-plugin-assemblyai | assemblyai.stt() | | Google Gemini (LLM, Realtime) | @voicelayer/agents-plugin-google | google.llm(), google.realtime() | | Silero (VAD) | @voicelayer/agents-plugin-silero | silero.vad() | | LiveKit (turn detection) | @voicelayer/agents-plugin-livekit | livekitTurn.english(), livekitTurn.multilingual() |

Each is a thin, versioned wrapper over the matching @livekit/agents-plugin-* package. Need a provider that isn't listed? Wrap any LiveKit plugin instance with wrap(...), or implement the STTProvider / LLMProvider / TTSProvider interfaces directly.

Bring your own LLM

Don't want a first-party model at all? Bring your own brain — your existing agent, a private model, a LangChain app, anything. VoiceLayer keeps doing STT, TTS, turn-taking, and telephony; your code does the thinking. Three ways, smallest first.

1. An in-process function — your existing agent as a callback (the "two lines" path):

import { defineAgent } from '@voicelayer/sdk';

export default await defineAgent({
  name: 'support',
  prompt: 'bridged to my brain',
  onQuery: async (text) => myExistingAgent.reply(text),  // ← your brain
}).start(import.meta.url);

onQuery gets the caller's final transcript and returns the reply — a string, or an AsyncIterable<string> to stream tokens (the SDK speaks the first sentence as soon as it lands). STT, TTS, and barge-in stay ours.

2. A direct endpoint — point at any public OpenAI-compatible URL:

import { defineAgent, connector } from '@voicelayer/sdk';

export default await defineAgent({
  name: 'support',
  prompt: 'You are a helpful assistant. Keep replies short.',
  models: {
    llm: connector.llm({
      url: 'https://your-brain.example.com/v1',   // OpenAI-compatible
      apiKey: process.env.BRAIN_API_KEY,
      model: 'your-model',
      fallbackText: 'Sorry, let me try that again.',
    }),
  },
}).start(import.meta.url);

Works with OpenAI, Azure, Together, Groq, vLLM, or a LiteLLM proxy in front of anything. The URL is https-only and SSRF-guarded; under the hood it reuses the proven LiveKit OpenAI client.

3. A private endpoint (tunnel) — keep your brain behind your firewall. Run the one-container vl-brain daemon — it dials out to us (no inbound ports) and LiteLLM is baked in to normalize any provider. The connector then shows up as a voice agent in the dashboard (its LLM is your brain; STT/TTS still swappable) — test it in the Playground, attach a number. No SDK code required. See the vl-brain daemon guide.

Connectors

Connectors are typed integrations with external systems. They show up on ctx.connectors and, when expose: true, every method also becomes an LLM-callable tool automatically.

There is no connector registry to install from — a connector is a plain object, so you write one against whatever API you already have:

import { defineAgent, type ConnectorInstance } from '@voicelayer/sdk';

const crm = {
  __connector: true as const,
  name: 'crm',
  // With `expose: true`, the LLM can call `crm_lookupPolicy` on its own.
  expose: true,
  api: {
    lookupPolicy: async ({ policyNumber }: { policyNumber: string }) => {
      const res = await fetch(`https://your-crm.example.com/policies/${policyNumber}`, {
        headers: { authorization: `Bearer ${process.env.CRM_TOKEN}` },
      });
      return res.json();
    },
  },
} satisfies ConnectorInstance;

defineAgent({
  // ...
  connectors: { crm },
});

Each method receives (args, ctx), so you can reach call state from inside a connector. When a ToolRouter is active, exposed connector methods are dispatched through Action Guard and audited like any other tool.

Running locally

node --import tsx agent.ts dev

This boots the worker against your LiveKit project and registers the agent with the VoiceLayer control plane, so you can call your number and iterate on the same file you will deploy. Set the environment variables listed under Production first.

A headless harness for asserting on process capture without audio is not part of the public API yet. Today, iterate by calling the agent, or drive the flow from the Playground in the dashboard.

Production

await start(import.meta.url) boots a LiveKit worker in the parent process and exports the resolved LiveKit agent definition for the child job runner that re-imports the same file. The same file. No deploy pipeline differences between local and prod beyond environment variables.

# Required. The worker runs on YOUR infrastructure and connects directly to
# LiveKit, so it needs your own LiveKit project credentials (LiveKit Cloud or
# self-hosted) alongside your VoiceLayer project key.
export VOICELAYER_API_KEY=...
export LIVEKIT_URL=...
export LIVEKIT_API_KEY=...
export LIVEKIT_API_SECRET=...

# Provider keys for the models your agent uses (or set them per project in the
# VoiceLayer dashboard's connections, resolved at call time):
export OPENAI_API_KEY=...
export DEEPGRAM_API_KEY=...

node agent.ts start

What's not in this SDK

• No "primitive" packages to import. The internal modularity is the platform team's problem, not yours.
• No multi-file boilerplate. One file per agent.
• No state-machine framework you have to learn. process is a field bag with validation; triggers are if/then rules. If you need branching flows, you use onUtterance or onCall.
• No "agent vs module" distinction. One declaration, one mental model.

Stability

The SDK is currently 0.x. APIs may change between minor versions while we find product-market fit. We will document every breaking change in the changelog.

At 1.0 we'll commit to semver and a stable public surface. Until then, expect movement.

Reference

• SDK documentation
• Dashboard, flow builder, and brain connectors
• Pricing — $0.05/min flat, providers billed at cost
• github.com/vlayers