Voice agents in code

What you'll buildCopy Anchor Link

A voice agent defined in code with @voicelayer/sdk: its prompt, models and tools in one file. VoiceLayer runs the call (speech, turn-taking, telephony, the guard). Your worker runs your code: it opens one outbound connection to VoiceLayer and answers when the call needs one of your functions. You need no LiveKit project and no provider keys in your process.

Prefer clicks? The flow builder builds the same kind of agent without code.

PrerequisitesCopy Anchor Link

• Node.js 22 or later.
• A secret API key in VOICELAYER_API_KEY, for the command line. It uploads and publishes your agent.
• For production only: a worker key (vlw_…) for one environment. Create it in the dashboard under Developers → API keys, choosing "The workers that run your agent code". A worker key can only open a session to VoiceLayer; it can call no API.

Step 1: InstallCopy Anchor Link

npm install @voicelayer/sdk

Step 2: Define the agentCopy Anchor Link

An agent is a manifest — the prompt, the models, and the tools it declares, as plain data that is uploaded and versioned — plus handlers: the functions inside it. defineAgent returns the agent and starts nothing.

// agent.ts
import { defineAgent, defineTool, httpTool, deepgram, openai } from '@voicelayer/sdk/v1';

export default defineAgent({
  name: 'front-desk',
  prompt: 'You answer the phone for Harbor Dental. Be brief and friendly.',
  greeting: 'Harbor Dental, how can I help?',
  capabilities: ['system.say', 'system.transfer_call'], // what your handlers may do to the call
  toolBindings: [], // dashboard tools this agent uses; [] means none

  models: {
    stt: deepgram.stt({ model: 'nova-3' }),
    llm: openai.llm({ model: 'gpt-4o' }),
    tts: deepgram.tts({ model: 'aura-2-harmonia-en' })
  },

  tools: {
    // code your worker runs: it can reach your private network
    ...defineTool({
      name: 'next_free_slot',
      description: 'Find the next free appointment slot',
      input: { day: 'string' },
      run: async ({ day }) => ({ day, time: '10:30' })
    }),
    // a declaration VoiceLayer runs: a fixed endpoint, no code
    ...httpTool({
      name: 'open_ticket',
      description: 'Open a support ticket',
      input: { summary: 'string' },
      url: 'https://example.com/api/tickets'
    })
  }
});

Provider keys (OpenAI, Deepgram, …) never live in your process. Add them in the dashboard under Settings → Provider accounts.

Step 3: Run it against the dev environmentCopy Anchor Link

voicelayer dev uploads the agent to your dev environment, serves its handlers and publishes. It prints how to reach the agent: the dashboard Playground, or a test number.

export VOICELAYER_API_KEY=vl_...
npx voicelayer dev ./agent.ts

You see the uploaded version and a Playground link. Editing a handler restarts the runner; editing the manifest uploads a new dev version.

Step 4: Use the call from a handlerCopy Anchor Link

Every handler gets ctx, the call context:

A handler keeps no call state in memory between invocations, because two invocations of one call can land on two processes. Keep call state in ctx.metadata or ctx.memory.

Each ctx action is checked against the system.* capabilities you declare; an undeclared one is refused. Handlers get the caller's phone number and words as placeholders (for example <PII_PHONE_1>) unless a tool sets sendRealValues: true.

Handlers that the call waits on have deadlines, so a slow or crashed worker never hangs a call: a tool has 10 seconds, after which the model gets a failed result.

Step 5: Deploy to productionCopy Anchor Link

In production, a worker serves the build that your deploy recorded in voicelayer.lock.json:

// worker.ts
import agent from './agent.js';

await agent.start(); // serves the build in voicelayer.lock.json; SIGTERM drains

export VOICELAYER_WORKER_KEY=vlw_...   # a worker key for ONE environment
node worker.js

A deploy is a new, immutable version. Roll it out in this order, so no call drops:

Several agents can share one process: startAgents([a, b, c]).

Test itCopy Anchor Link

Test a handler as a plain function with @voicelayer/sdk/testing, with no network:

import { assertAgent, invoke, testContext } from '@voicelayer/sdk/testing';
import agent from './agent.js';

assertAgent(agent); // the manifest builds and passes the upload's checks
const slot = await invoke(agent, 'tool.next_free_slot', { day: 'Monday' }, testContext());
console.log(slot); // { day: 'Monday', time: '10:30' }

End to end, run voicelayer dev and talk to the agent in the Playground. See Test an agent.

Command lineCopy Anchor Link

Common errorsCopy Anchor Link

Next stepsCopy Anchor Link

• Brains in code: use your own model or agent framework as the call's brain.
• How an agent runs: flow agents and code agents side by side.
• Transfers: send a caller to a person.