Deepgram Voice Agent

Voice agent SDK and embeddable widget for the Deepgram Agent API.

@deepgram/agents  ←  @deepgram/react (external)  ←  @deepgram/ui (external)  ←  @deepgram/agents-widget

Status

These packages are pre-1.0. Interfaces may change between minor versions, and releases are cut as the libraries evolve rather than on a fixed schedule. The packages in this family build on the Deepgram Voice Agent API to provide browser SDKs, React hooks and UI components, and an embeddable widget.

Packages

Package	Description
@deepgram/agents	Core SDK -- WebSocket session, microphone capture, audio playback
@deepgram/agents-widget	Self-contained widget (UMD + ESM) -- drop into any page, no framework needed

React hooks and UI components live in their own repos:

Package	Repo
@deepgram/react	React provider and hooks for agent state, conversation, controls
@deepgram/ui	Pre-built React UI components with Tailwind CSS theming

Quick Start

Widget (no framework)

npm install @deepgram/agents-widget

import { init } from "@deepgram/agents-widget";

init({
  tokenFactory: () => fetch('/api/deepgram-token').then(r => r.text()),
  agent: { think: { provider: { type: 'open_ai', model: 'gpt-4o-mini' } } },
});

The package also ships a UMD bundle at dist/widget.umd.js for <script>-tag usage; host it from your own server.

React

npm install @deepgram/ui react react-dom

import {
  AgentProvider,
  AgentConversation,
  AgentMessage,
  AgentStartButton,
  AgentTextInput,
  useAgentConversation,
} from "@deepgram/ui";

function Conversation() {
  const { conversation } = useAgentConversation();
  return (
    <AgentConversation>
      {conversation.map((entry) => (
        <AgentMessage key={entry.id} entry={entry} />
      ))}
    </AgentConversation>
  );
}

function App() {
  return (
    <AgentProvider
      config={{
        auth: { tokenFactory: () => fetch('/api/deepgram-token').then(r => r.text()) },
        agent: { think: { provider: { type: 'open_ai', model: 'gpt-4o-mini' } } },
      }}
    >
      <div data-dg-agent>
        <AgentStartButton />
        <Conversation />
        <AgentTextInput />
      </div>
    </AgentProvider>
  );
}

Styles are embedded in the JavaScript bundle and injected automatically; no separate CSS import is required. The injected styles, including the theme variables and dark-mode behavior, apply only inside an element that carries the data-dg-agent attribute, so keep the components inside that wrapper.

SDK only

import { AgentSession, AgentMicrophone, AgentPlayer } from "@deepgram/agents";

const session = new AgentSession({
  auth: { tokenFactory: () => fetch('/api/deepgram-token').then(r => r.text()) },
  agent: { think: { provider: { type: 'open_ai', model: 'gpt-4o-mini' } } },
});

const player = new AgentPlayer();
session.on("audio", (chunk) => player.queue(chunk));

const mic = new AgentMicrophone((data) => session.sendAudio(data));
await session.connect();
await mic.start();

Authentication

The SDK authenticates via the Sec-WebSocket-Protocol header (not URL query params). Two auth modes:

• API key (server-side only): { apiKey: "your-deepgram-api-key" }
• Token factory (browser-safe): { tokenFactory: () => fetch('/api/token').then(r => r.text()) }

The token factory is called before every connection and reconnection attempt, so tokens can be short-lived and rotated automatically.

Theming

All styling comes from @deepgram/ui's compiled Tailwind CSS. The widget exposes 26 CSS custom properties on [data-dg-agent] for runtime theming — see the widget README for the full list.

Examples

17 examples live in examples/:

Range	Type	Examples
01-07	Widget (TypeScript)	sidebar, inline, floating, button, embedded, orb, floating-orb
10-15	React	sidebar, inline, floating, standalone UI, voice button, orb
20-23	UMD bundle	sidebar, inline, floating, console

Run locally:

bun run dev:examples    # Vite dev server on :5173

Live demo: deepgram-agent-examples.fly.dev

Roadmap

@deepgram/react and @deepgram/ui have been extracted into their own repos as generic Deepgram browser primitives:

Package	Repo
@deepgram/agents	This repo (packages/sdk/)
@deepgram/agents-widget	This repo (packages/widget/)
@deepgram/react	deepgram/react
@deepgram/ui	deepgram/ui
@deepgram/browser	Planned: browser instrumentation SDK (non-agent), may re-export agent bits

Development

Prerequisites: Bun 1.3+

git clone https://github.com/deepgram/agent.git
cd agent
bun install

bun run build              # Build all packages
bun run typecheck           # Type-check all packages
bun run test                # Run tests
bun run dev:examples        # Run examples dev server (:5173)

Deployment

The examples app deploys to Fly.io:

fly deploy    # deploys to deepgram-agent-examples.fly.dev

License

MIT -- see LICENSE