JavaScript SDK

Installation

npm install @deepgram/agents

Usage

Connect to a Deepgram voice agent, capture microphone audio, and play back the agent’s speech:

import { AgentSession, AgentMicrophone, AgentPlayer } from "@deepgram/agents";
const session = new AgentSession({
  auth: {
    tokenFactory: () => fetch("/api/deepgram-token").then((r) => r.text()),
  },
  agent: "YOUR_AGENT_ID",
});
const player = new AgentPlayer();
const mic = new AgentMicrophone((data) => session.sendAudio(data));
// Play agent audio
session.on("audio", (chunk) => player.queue(chunk));
// Interrupt playback when the user speaks (barge-in)
session.on("user-started-speaking", () => player.interrupt());
// Log conversation turns
session.on("conversation-text", (msg) => {
  console.log(`${msg.role}: ${msg.content}`);
});
await session.connect();
await mic.start();

Replace YOUR_AGENT_ID with a Reusable Agent Configuration UUID, or pass an inline agent config object instead. See Agent Configuration for both patterns.

AgentSession

The core class that manages the WebSocket connection to the Voice Agent API. It handles authentication, automatic reconnection with exponential backoff, keep-alive pings, and audio buffering before the server acknowledges settings.

import { AgentSession } from "@deepgram/agents";
const session = new AgentSession(config);

Configuration

const session = new AgentSession({
  // Required — authentication
  auth: {
    tokenFactory: () => fetch("/api/token").then((r) => r.text()),
  },
  // Required — agent ID or inline settings
  agent: "YOUR_AGENT_ID",
  // Optional — audio format
  audio: {
    input: { encoding: "linear16", sampleRate: 16_000 },
    output: { encoding: "linear16", sampleRate: 24_000 },
  },
  // Optional — reconnection behavior
  reconnect: {
    enabled: true,
    maxAttempts: 8,
    baseDelay: 500,
    maxDelay: 30_000,
    jitter: true,
  },
  // Optional — keep-alive ping interval (ms)
  keepAliveInterval: 10_000,
  // Optional — custom WebSocket URL (for proxies)
  url: undefined,
});

Auth options:

Agent options:

The agent field accepts either a string agent ID from the Deepgram Console or an inline AgentSettingsObject with listen, think, and speak configuration.

Audio options:

Reconnection options:

Connection States

The state property reflects the current connection lifecycle:

session.state; // "idle" | "connecting" | "connected" | "reconnecting" | "disconnected"

• idle — session created but connect() has not been called.
• connecting — WebSocket connection attempt in progress.
• connected — WebSocket is open and the session is active.
• reconnecting — connection lost; attempting to reconnect with backoff.
• disconnected — connection closed and no further reconnection attempts will be made.

Methods

connect(): Promise<void> — establish the WebSocket connection to the agent. Resolves when the socket is open. The SDK automatically sends a Settings message after receiving the Welcome event.

await session.connect();

disconnect(): void — close the connection and cancel any pending reconnection attempts.

session.disconnect();

sendAudio(data: ArrayBuffer): void — send a PCM audio frame to the agent. Frames sent before the server fires settings-applied are queued internally and flushed automatically once the agent is ready. This prevents dropped frames during connection setup.

session.sendAudio(audioBuffer);

injectUserMessage(content: string): void — inject a text message into the conversation as the user.

session.injectUserMessage("What's the weather like?");

injectAgentMessage(message: string): void — inject a text message into the conversation as the agent.

session.injectAgentMessage("Let me look that up for you.");

updatePrompt(prompt: string): void — change the agent’s system prompt mid-session.

session.updatePrompt("You are now a customer support agent.");

updateSpeak(settings): void — change TTS settings mid-session. Accepts a SpeakSettings object or an array.

session.updateSpeak({
  provider: { type: "deepgram", version: "v2", model: "flux-alexis-en" },
});

updateThink(settings): void — change LLM settings mid-session. Accepts a ThinkSettings object or an array.

session.updateThink({
  provider: { type: "open_ai", model: "gpt-4o" },
});

sendFunctionCallResponse(id, name, content): void — respond to a function call request from the agent. See Function Calls for a complete example.

session.sendFunctionCallResponse(fn.id, fn.name, JSON.stringify(result));

getId(): string | null — returns the session ID assigned by the server. Available after the welcome event fires. Returns null before connection.

const sessionId = session.getId();

Events

Subscribe with session.on(event, callback) and unsubscribe with session.off(event, callback).

Connection lifecycle:

Agent protocol:

Audio:

Errors:

AgentMicrophone

Captures PCM audio from the user’s microphone using the Web Audio API.

import { AgentMicrophone } from "@deepgram/agents";
const mic = new AgentMicrophone(
  (data) => session.sendAudio(data),
  {
    sampleRate: 16_000,
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  }
);
await mic.start();

The first argument is a callback invoked with each captured audio frame as an ArrayBuffer. Pass session.sendAudio to stream audio directly to the agent.

Options

Methods

start(): Promise<void> — request microphone permission via getUserMedia and begin capturing audio frames.

await mic.start();

stop(): void — stop capturing audio, disconnect the audio worklet, and release the microphone device.

mic.stop();

mute(): void — pause audio transmission without releasing the microphone. The device remains active but frames are not forwarded.

mic.mute();

unmute(): void — resume audio transmission after a mute() call.

mic.unmute();

muted: boolean — read-only property indicating whether the microphone is currently muted.

getInputVolume(): number — returns the current RMS input volume level as a value between 0 and 1. Call per animation frame for real-time visualizations.

function animate() {
  const volume = mic.getInputVolume();
  drawMeter(volume);
  requestAnimationFrame(animate);
}

getInputByteFrequencyData(): Uint8Array — returns frequency domain data as a Uint8Array with values 0—255. Use for spectrum or waveform visualizations.

Events

Subscribe with mic.on(event, callback) and unsubscribe with mic.off(event, callback).

AgentPlayer

Decodes and plays PCM audio received from the agent. Maintains a playback queue with interrupt support for barge-in, and exposes volume and frequency analysis APIs for building custom visualizations.

import { AgentPlayer } from "@deepgram/agents";
const player = new AgentPlayer({ sampleRate: 24_000 });
session.on("audio", (chunk) => player.queue(chunk));
session.on("user-started-speaking", () => player.interrupt());

Options

Methods

queue(data: ArrayBuffer): void — decode a PCM audio buffer and add it to the playback queue. Buffers are played in order with sample-accurate scheduling.

interrupt(): void — immediately stop playback and discard all queued audio. Use when the user starts speaking to enable barge-in.

getRemainingPlaybackTime(): number — returns the number of seconds of audio still queued for playback. Returns 0 when idle. Useful for delaying mode transitions until the agent finishes speaking.

mute(): void — stop playback and discard queued audio. Subsequent calls to queue() are silently dropped until unmute() is called.

unmute(): void — resume accepting and playing queued audio.

muted: boolean — read-only property indicating whether the player is currently muted.

setVolume(volume: number): void — set the playback volume as a value between 0 and 1. Default: 1.

player.setVolume(0.5);

volume: number — read-only property returning the current playback volume (0—1).

getOutputVolume(): number — returns the current RMS output volume level as a value between 0 and 1. Call per animation frame for real-time visualizations.

getOutputByteFrequencyData(): Uint8Array — returns frequency domain data as a Uint8Array with values 0—255. Use for spectrum visualizations of the agent’s speech.

dispose(): void — close the underlying AudioContext and free resources. Call when the session is no longer needed.

Function Calls

The agent can request client-side function calls during a conversation. Listen for the function-call-request event, execute the requested function, and respond with the result using sendFunctionCallResponse.

session.on("function-call-request", async (msg) => {
  for (const fn of msg.functions) {
    let result;
    switch (fn.name) {
      case "get_weather":
        result = await fetchWeather(JSON.parse(fn.input));
        break;
      case "book_appointment":
        result = await bookAppointment(JSON.parse(fn.input));
        break;
      default:
        result = { error: `Unknown function: ${fn.name}` };
    }
    session.sendFunctionCallResponse(fn.id, fn.name, JSON.stringify(result));
  }
});

Each item in the functions array contains:

The agent pauses until it receives a response for each requested function call.

Token Caching

The SDK caches authentication tokens internally. When you provide a tokenFactory in the auth configuration, the AgentSession wraps it in a caching layer that avoids requesting a new token on every reconnect. Tokens are cached for 4 minutes by default, which is safe for Deepgram’s 5-minute short-lived keys. The cache is automatically invalidated before each reconnection attempt to ensure a fresh token is available.

const session = new AgentSession({
  auth: {
    // This function is only called when the cache is empty or expired
    tokenFactory: async () => {
      const res = await fetch("/api/deepgram-token");
      return res.text();
    },
  },
  agent: "YOUR_AGENT_ID",
});

No additional setup is required. The caching behavior is automatic and transparent.