Skip to content

README.md

Latest commit

 

History

History
122 lines (94 loc) · 4.25 KB

README.md

File metadata and controls

122 lines (94 loc) · 4.25 KB
Raw

@deepgram/react

npm version license CI

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

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