@deepgram/react

React hooks and provider for the Deepgram Voice Agent API. Manages connection lifecycle, microphone capture, audio playback, conversation state, and mode tracking.

Install

npm install @deepgram/react @deepgram/agents

Quick Start

import { AgentProvider, useAgentState, useAgentConversation } from "@deepgram/react";

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' } },
      }}
    >
      <VoiceAgent />
    </AgentProvider>
  );
}

function VoiceAgent() {
  const { state, start, stop } = useAgentState();
  const { conversation } = useAgentConversation();

  return (
    <div>
      <button onClick={state === "idle" ? start : stop}>
        {state === "idle" ? "Start" : "Stop"}
      </button>
      {conversation.map((entry) => (
        <p key={entry.id}><b>{entry.role}:</b> {entry.content}</p>
      ))}
    </div>
  );
}

Hooks

Hook	Purpose
useAgentState	Connection state (idle, connecting, connected, etc.) and start/stop controls
useAgentMode	Speaking/listening mode tracking
useAgentConversation	Conversation transcript and sendUserMessage
useAgentMicrophone	Mic state, mute controls, input volume
useAgentPlayer	Audio playback state, mute controls, output volume
useAgentControls	Stable action methods (never change identity)
useAgentClientTool	Register client-side function call handlers scoped to component lifecycle
useAgentSession	Direct access to the underlying AgentSession (escape hatch)
useDeepgramAgent	Standalone hook -- no provider needed

See the package README for full API documentation.

Related Packages

Package	Repo	Description
@deepgram/agents	deepgram/agent	Core SDK -- WebSocket session, microphone capture, audio playback
@deepgram/ui	deepgram/ui	Pre-built React UI components with Tailwind CSS theming
@deepgram/agents-widget	deepgram/agent	Self-contained widget (UMD + ESM)

Documentation

• Deepgram Voice Agent docs
• API reference
• @deepgram/ui -- pre-built components

Development

Prerequisites: Bun 1.3+

This package depends on @deepgram/agents via a file: pointer. Clone the agent repo as a sibling:

git clone git@github.com:deepgram/agent.git ../agent
cd ../agent && bun install && bun run build

Then:

git clone git@github.com:deepgram/react.git
cd react
bun install

bun run build       # Build @deepgram/react
bun run typecheck   # Type-check
bun run test        # Run tests
bun run dev         # Watch-build

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT -- see LICENSE