> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Node JS

> The Zero Runtime Node JS SDK: build voice AI agents in JavaScript or TypeScript on Node.js 20.11+ with typed, ESM-first APIs.

## Requirements

* Node.js 20.11+
* A Zero Runtime auth token from the [dashboard](https://app.zeroruntime.ai/)
* API keys for the providers you use

## Install

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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

* Extend `Agent` and implement `on_enter()` and `on_exit()`.
* Use `Pipeline()` and provider functions directly.
* Use `function_tool()` to define tools.
* Access the current session with `this.session!` inside agents.
* Import core APIs from `@zeroruntime/js-sdk` and providers from `@zeroruntime/js-sdk/plugins`.

## Example

```typescript title="main.ts" theme={null}
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.

<Note>
  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.
</Note>

## API reference

<Card title="Node JS SDK API reference" icon="node-js" href="/api-reference/node-js/overview" horizontal>
  Every export, type, and option in the Node JS SDK.
</Card>

The [Quickstart](/quickstarts/build-your-first-voice-agent) shows a complete agent. Runnable examples are at
[zeroruntime-js-examples](https://github.com/ZeroRuntimeAI/zeroruntime-js-examples).