Node JS

Requirements

Node.js 20.11+
A Zero Runtime auth token from the dashboard
API keys for the providers you use

Install

npm install @zeroruntime/js-sdk

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. Every provider ships with the SDK; most need no extra package, because their credential is a string you set in the environment.

npm install -D tsx typescript

Connect to the Runtime

Point the worker at your runtime address, and set your auth token, using the values from the dashboard:

export ZERORUNTIME_TARGET=us2.zeroruntime.ai:443
export ZERORUNTIME_AUTH_TOKEN=<your-auth-token>

The SDK reads a .env from the working directory if you add import 'dotenv/config'; at the top of your entrypoint.

Conventions

The SDK is ESM-only. Use "type": "module" in your package.json, or .mjs/.ts files.
Agents subclass Agent and implement the async on_enter() and on_exit() hooks. Names mirror the Python SDK, so options and hooks are snake_case in both.
Pipeline and every provider are factory calls, not constructors — no new — and each takes a single options object, for example GoogleLLM({ model: 'gemini-2.5-flash' }).
Core APIs (Agent, Pipeline, Room, Sip, serve, invoke, function_tool) are imported from @zeroruntime/js-sdk.
Provider plugins come from @zeroruntime/js-sdk/plugins (direct to the vendor, with your key) or @zeroruntime/js-sdk/inference (the same providers through the Zero Runtime gateway, with only your Zero Runtime token). The names mirror each other, so swapping the import swaps who makes the call and who is billed.
Tools are built with function_tool({ name, description, parameters, execute }). JavaScript cannot read parameter types at runtime, so you describe them yourself. A tool assigned to a field on your agent class is registered automatically; tools defined elsewhere go in the tools array.
Inside a hook or tool, this.session! is the live Session. Outside the class, reach it with current_session().

Example

main.ts

import 'dotenv/config';

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';

const AGENT_ID = 'assistant';

class VoiceAgent extends Agent {
  constructor() {
    super({
      agent_id: AGENT_ID,
      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?');
  }

  async on_exit(): Promise<void> {
    await this.session!.say('Goodbye!');
  }

  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(AGENT_ID, {
    room: Room({ name: 'Cascade Agent', playground: true }),
  });
}

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

Run it with npx tsx main.ts. The playground URL is printed once, on stdout — open it to talk to the agent.

Pass the agent class to serve(), not an instance. serve() builds a fresh agent and pipeline per call, which is what keeps per-call state correct under concurrent calls.

API reference

Node JS SDK API reference

Every export, type, and option in the Node JS SDK.

The Quickstart shows a complete agent. Runnable examples are at zeroruntime-js-examples.

Get started

Quickstarts

SDKs

Requirements

Install

Connect to the Runtime

Conventions

Example

API reference

Node JS SDK API reference

​Requirements

​Install

​Connect to the Runtime

​Conventions

​Example

​API reference

Node JS SDK API reference

Requirements

Install

Connect to the Runtime

Conventions

Example

API reference