@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();
  const handleStart = async () => {
    try {
      await start();
    } catch (error) {
      console.error("Failed to start voice agent", error);
    }
  };

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

config, playerSampleRate, and the initial autoStart value establish the provider session for that component lifetime. Use the runtime update methods for supported listen, think, speak, and prompt changes rather than changing config in place.

Hooks

Hook	Purpose
useAgentState	Connection state (idle, connecting, connected, etc.) and start/stop controls
useAgentMode	Listening/thinking/speaking mode tracking
useAgentConversation	Conversation transcript plus user and agent messages
useAgentMicrophone	Mic state, mute controls, input volume
useAgentPlayer	Audio playback state, mute controls, output volume
useAgentControls	Grouped lifecycle, messaging, settings, and mute controls
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. See the migration guide when upgrading from 0.1 to 0.2.

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
• Migration guide
• @deepgram/ui -- pre-built components

Development

Prerequisites: Bun 1.3+

The published package depends on the npm release of @deepgram/agents. For coordinated local development, you can optionally clone a sibling checkout; this repository's TypeScript config uses it when present and otherwise resolves the npm package:

git clone [email protected]:deepgram/agent.git ../agent
cd ../agent && bun install && bun run build

Then:

git clone [email protected]: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