@zeroruntime/js-sdk

Build real-time voice agents in JavaScript and TypeScript. You describe the agent - instructions, tools, and a pipeline of providers - and the runtime runs it.

Install

npm install @zeroruntime/js-sdk

or pin the version:

npm install @zeroruntime/js-sdk

Requires Node 20.11 or newer. The package ships compiled JavaScript plus complete type declarations, so both languages are first class: TypeScript runs directly with tsx, JavaScript needs no build step at all.

Most providers need no extra package: their credential is a string you set in the environment, so the base install is enough.

Quickstart

import * as zeroruntime from '@zeroruntime/js-sdk';
import { Agent, Pipeline, Room, function_tool } from '@zeroruntime/js-sdk';
import { TurnDetector } from '@zeroruntime/js-sdk/inference';
import { CartesiaTTS, DeepgramSTT, GoogleLLM, SileroVAD } from '@zeroruntime/js-sdk/plugins';

// The agent registers as ZERORUNTIME_AGENT_ID (default 'zeroruntime_agent').
// Agent cloud sets it to the deployment's agent id.

class VoiceAgent extends Agent {
  constructor() {
    super({
      instructions: 'You are a helpful voice assistant.',
      pipeline: Pipeline({
        stt: DeepgramSTT(),
        llm: GoogleLLM(),
        tts: CartesiaTTS(),
        vad: SileroVAD(),
        turn_detector: TurnDetector(),
      }),
    });
  }

  async on_enter(): Promise<void> {
    await this.session!.say('Hello, how can I help you today?');
  }

  get_weather = function_tool({
    name: 'get_weather',
    description: 'Fetch the current weather for a location.',
    parameters: {
      latitude: { type: 'string', description: 'Latitude of the location. Estimate it; do not ask.' },
      longitude: { type: 'string', description: 'Longitude of the location. Estimate it; do not ask.' },
    },
    execute: async ({ latitude, longitude }) => ({ latitude, longitude, temperature_c: 28 }),
  });
}

async function invoke_agent(): Promise<void> {
  await zeroruntime.invoke({
    room: Room({ name: 'Cascade Agent', playground: true }),
  });
}

await zeroruntime.serve(VoiceAgent, { on_ready: invoke_agent });

Run it and the playground URL is printed once, on stdout. Open it to talk to the agent.

Credentials

Set your runtime token in the environment before serving:

export ZERORUNTIME_AUTH_TOKEN="..."

Vendor keys go in the environment too, one per provider you use — each provider names the variable it reads when the key is missing.

Providers

@zeroruntime/js-sdk/plugins calls the vendor directly with your key on your account. @zeroruntime/js-sdk/inference reaches a subset of the same providers through the runtime gateway instead. The names mirror each other, so swapping the import swaps who makes the call and who is billed:

import { DeepgramSTT } from '@zeroruntime/js-sdk/plugins';    // your Deepgram account
import { DeepgramSTT } from '@zeroruntime/js-sdk/inference';  // through the gateway