# React Hooks & Provider

:::callout{intent="info"}
Looking for pre-built UI components? See [React UI Components](/guides/self-hosted-deployments-3-browser-agent-react-ui). For the core JavaScript SDK, see [JavaScript](/guides/self-hosted-deployments-3-browser-agent-javascript).
:::

## Installation

```shell
npm install @deepgram/react
```

:::callout{intent="note"}
`@deepgram/react` lists `@deepgram/agents` as a dependency and re-exports the SDK types you need (`AgentSessionConfig`, `AgentSettingsObject`, `MicrophoneOptions`, and the rest), so a single `npm install @deepgram/react` is all you need for the React layer. If you want direct access to the SDK classes (`AgentSession`, `AgentMicrophone`, `AgentPlayer`), import them from `@deepgram/agents`.
:::

## Usage

Wrap your component tree in `AgentProvider`, then use focused hooks to access the state and controls your component needs.

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

function App() {
  return (
    <AgentProvider
      config={{
        auth: { tokenFactory: () => fetch("/api/token").then((r) => r.text()) },
        agent: "YOUR_AGENT_ID",
      }}
    >
      <VoiceAgent />
    </AgentProvider>
  );
}

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

  return (
    <div>
      <p>Mode: {mode}</p>
      <button onClick={() => (state === "connected" ? stop() : start())}>
        {state === "connected" ? "Disconnect" : "Connect"}
      </button>
      <ul>
        {conversation.map((msg) => (
          <li key={msg.id}>
            <strong>{msg.role}:</strong> {msg.content}
          </li>
        ))}
      </ul>
    </div>
  );
}
```

Replace `YOUR_AGENT_ID` with a [Reusable Agent Configuration](/guides/self-hosted-deployments-3-reusable-agent-configurations) UUID, or pass an inline agent config object instead. See [Agent Configuration](/guides/self-hosted-deployments-3-browser-agent-overview#agent-configuration) for both patterns.

## AgentProvider

The provider creates and manages `AgentSession`, `AgentMicrophone`, and `AgentPlayer` instances. All hooks below must be called within an `AgentProvider`.

```tsx
<AgentProvider
  config={agentSessionConfig}
  microphone={true}
  microphoneOptions={{ sampleRate: 16_000 }}
  tts={true}
  playerSampleRate={24_000}
  autoStart={false}
  onFunctionCall={handleFunctionCall}
>
  {children}
</AgentProvider>
```

### Props

| Prop                 | Type                                                  | Default     | Description                                                                                                                                                                                                   |
| -------------------- | ----------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config`             | `AgentSessionConfig`                                  | required    | Session configuration. See [JavaScript SDK](/guides/self-hosted-deployments-3-browser-agent-javascript) for all options.                                                                                      |
| `microphone`         | `boolean`                                             | `true`      | Enable microphone capture.                                                                                                                                                                                    |
| `microphoneOptions`  | `MicrophoneOptions`                                   | `undefined` | Options passed to `AgentMicrophone` (sample rate, echo cancellation, noise suppression, auto gain control). See [JavaScript SDK](/guides/self-hosted-deployments-3-browser-agent-javascript#agentmicrophone). |
| `tts`                | `boolean`                                             | `true`      | Enable TTS audio playback.                                                                                                                                                                                    |
| `playerSampleRate`   | `number`                                              | `24000`     | Sample rate for the audio player.                                                                                                                                                                             |
| `autoStart`          | `boolean`                                             | `false`     | Connect to the agent immediately on mount.                                                                                                                                                                    |
| `onFunctionCall`     | `(fn: FunctionCallItem) => Promise<string> \| string` | `undefined` | Default handler for agent function call requests. Dynamic tools registered with `useAgentClientTool` take priority over this prop.                                                                            |
| `onError`            | `(message: AgentErrorMessage) => void`                | `undefined` | Handler for server-reported agent errors.                                                                                                                                                                     |
| `onSdkError`         | `(error: Error) => void`                              | `undefined` | Handler for SDK transport errors and automatic-start failures.                                                                                                                                                |
| `onWarning`          | `(message: AgentWarningMessage) => void`              | `undefined` | Handler for server-reported agent warnings.                                                                                                                                                                   |
| `onLatencyReport`    | `(message: LatencyReportMessage) => void`             | `undefined` | Handler for agent latency reports.                                                                                                                                                                            |
| `onInjectionRefused` | `(message: InjectionRefusedMessage) => void`          | `undefined` | Handler when the server rejects an injected message.                                                                                                                                                          |
| `onListenUpdated`    | `(message: ListenUpdatedMessage) => void`             | `undefined` | Handler when the server confirms a `updateListen()` request.                                                                                                                                                  |
| `onPromptUpdated`    | `(message: PromptUpdatedMessage) => void`             | `undefined` | Handler when the server confirms a `updatePrompt()` request.                                                                                                                                                  |
| `onSpeakUpdated`     | `(message: SpeakUpdatedMessage) => void`              | `undefined` | Handler when the server confirms a `updateSpeak()` request.                                                                                                                                                   |
| `onThinkUpdated`     | `(message: ThinkUpdatedMessage) => void`              | `undefined` | Handler when the server confirms a `updateThink()` request.                                                                                                                                                   |
| `onHistory`          | `(message: HistoryMessage) => void`                   | `undefined` | Handler for conversation history received from the server.                                                                                                                                                    |

## Hooks

### useAgentState

Connection state and lifecycle controls.

```tsx
const {
  state,           // "idle" | "connecting" | "connected" | "reconnecting" | "disconnected"
  isIdle,          // true when state === "idle"
  isConnecting,    // true when state === "connecting"
  isConnected,     // true when state === "connected"
  isReconnecting,  // true when state === "reconnecting"
  isDisconnected,  // true when state === "disconnected"
  isActive,        // true when connected, connecting, or reconnecting
  start,           // () => Promise<void> — connect session + open mic
  stop,            // () => void — disconnect + close mic
} = useAgentState();
```

### useAgentConversation

Conversation history and text input.

```tsx
const {
  conversation,       // ConversationEntry[]
  clearConversation,  // () => void
  sendUserMessage,    // (text: string) => void — inject a text message as the user
  sendAgentMessage,   // (message: string, behavior?: "default" | "queue" | "interrupt") => void
} = useAgentConversation();
```

Each `ConversationEntry` contains:

| Field     | Type                    | Description                      |
| --------- | ----------------------- | -------------------------------- |
| `id`      | `string`                | Unique identifier for the entry. |
| `role`    | `"user" \| "assistant"` | Who said it.                     |
| `content` | `string`                | The message text.                |

### useAgentMode

Tracks the agent's speaking/listening mode with playback awareness. The mode transitions from `"speaking"` to `"listening"` only after all queued audio finishes playing in the browser, not when the server sends the `AgentAudioDone` event. This prevents the UI from showing "listening" while the agent's voice is still audible.

```tsx
const {
  mode,        // "idle" | "listening" | "thinking" | "speaking"
  isSpeaking,  // true when mode === "speaking"
  isListening, // true when mode === "listening"
  isThinking,  // true when mode === "thinking"
} = useAgentMode();
```

:::callout{intent="note"}
The playback-aware transition is automatic. The provider measures `AgentPlayer.getRemainingPlaybackTime()` when the server signals audio-done, then delays the mode switch by that duration. No configuration needed.
:::

### useAgentMicrophone

Microphone state, mute controls, and input volume.

```tsx
const {
  micActive,       // true when hardware is open
  micMuted,        // true when muted (stream still open, not sending audio)
  setMicMuted,     // (muted: boolean) => void
  toggle,          // () => void — toggle mute state
  enabled,         // false when microphone={false} on provider — mic is fully disabled
  getInputVolume,  // () => number — returns 0-1, call per animation frame
} = useAgentMicrophone();
```

:::callout{intent="note"}
`getInputVolume()` reads the current microphone level without triggering a re-render. Call it inside `requestAnimationFrame` or a canvas draw loop for smooth audio visualizations.
:::

### useAgentPlayer

Audio playback state, mute controls, and output volume.

```tsx
const {
  outputMuted,      // true when muted
  setOutputMuted,   // (muted: boolean) => void
  toggle,           // () => void — toggle mute state
  enabled,          // false when tts={false} on provider — playback is fully disabled
  getOutputVolume,  // () => number — returns 0-1, call per animation frame
} = useAgentPlayer();
```

### useAgentControls

Action methods only, no state. Like the other focused hooks, it consumes `AgentContext`, so its component re-renders when the provider value changes.

Use this for components that dispatch commands but do not display state, such as a toolbar or keyboard shortcut handler.

```tsx
const {
  start,              // () => Promise<void>
  stop,               // () => void
  sendUserMessage,    // (text: string) => void
  sendAgentMessage,   // (message: string, behavior?: "default" | "queue" | "interrupt") => void
  updateListen,       // (listen: ListenSettings) => void
  updateThink,        // (think: ThinkSettings | ThinkSettings[]) => void
  updateSpeak,        // (speak: SpeakSettings | SpeakSettings[]) => void
  updatePrompt,       // (prompt: string) => void
  clearConversation,  // () => void
  setMicMuted,        // (muted: boolean) => void
  setOutputMuted,     // (muted: boolean) => void
} = useAgentControls();
```

```tsx
useEffect(() => {
  const handleKey = (e: KeyboardEvent) => {
    if (e.key === "m") setMicMuted(true);
  };
  window.addEventListener("keydown", handleKey);
  return () => window.removeEventListener("keydown", handleKey);
}, [setMicMuted]);
```

### useAgentClientTool

Register a client-side tool handler scoped to the component lifecycle. The handler is automatically unregistered when the component unmounts, so tools only exist while the component that provides them is mounted.

```tsx
useAgentClientTool(
  name: string,
  handler: (fn: FunctionCallItem) => Promise<string> | string
): void
```

Dynamic tools registered with this hook take priority over the `onFunctionCall` prop on `AgentProvider`. If no dynamic tool matches the requested function name, the provider falls back to `onFunctionCall`.

```tsx
function WeatherWidget() {
  const [weather, setWeather] = useState(null);

  useAgentClientTool("get_weather", async (fn) => {
    const { city } = JSON.parse(fn.input);
    const data = await fetchWeather(city);
    setWeather(data);
    return JSON.stringify(data);
  });

  return weather ? <WeatherCard data={weather} /> : null;
}
```

The handler always captures the latest closure, so referencing component state inside the handler works without stale-state issues.

```tsx
function MapComponent() {
  const [location, setLocation] = useState({ lat: 0, lng: 0 });

  // Always reads the current location value
  useAgentClientTool("getLocation", () => {
    return JSON.stringify(location);
  });

  useAgentClientTool("setLocation", (fn) => {
    const coords = JSON.parse(fn.input);
    setLocation(coords);
    return JSON.stringify({ ok: true });
  });

  return <Map center={location} />;
}
```

### useAgentSession

Raw escape hatch to the underlying `AgentSession` instance. Use for advanced operations not covered by other hooks, such as listening to custom events or calling lower-level session methods.

```tsx
const session = useAgentSession();

useEffect(() => {
  const handler = (msg) => console.log("Agent thinking:", msg);
  session.on("agent-thinking", handler);
  return () => session.off("agent-thinking", handler);
}, [session]);
```

### useAgentContext

Access the full context value. Prefer the focused hooks above for a smaller, purpose-specific API surface. This hook is available when you need several unrelated values without importing multiple hooks.

```tsx
const ctx = useAgentContext();
// ctx.state, ctx.mode, ctx.conversation, ctx.micMuted, etc.
```

## Standalone Hook

For simpler apps that do not need shared state across multiple components, `useDeepgramAgent` manages the session, microphone, and player internally without requiring a provider.

```tsx
import { useDeepgramAgent } from "@deepgram/react";

function VoiceAgent() {
  const {
    state,
    conversation,
    micActive,
    outputMuted,
    start,
    stop,
    setMicMuted,
    setOutputMuted,
    sendUserMessage,
    interrupt,
  } = useDeepgramAgent({
    config: {
      auth: { tokenFactory: () => fetch("/api/token").then((r) => r.text()) },
      agent: "YOUR_AGENT_ID",
    },
    micOptions: { sampleRate: 16_000 },
    playerSampleRate: 24_000,
    onFunctionCall: async (fn) => {
      return JSON.stringify({ result: "ok" });
    },
  });

  return (
    <div>
      <button onClick={() => (state === "connected" ? stop() : start())}>
        {state === "connected" ? "Disconnect" : "Start"}
      </button>
      <ul>
        {conversation.map((msg) => (
          <li key={msg.id}>
            <strong>{msg.role}:</strong> {msg.content}
          </li>
        ))}
      </ul>
    </div>
  );
}
```

### Options

| Option               | Type                                         | Default     | Description                                                                                |
| -------------------- | -------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `config`             | `AgentSessionConfig`                         | required    | Session configuration (auth, agent ID, settings).                                          |
| `micOptions`         | `MicrophoneOptions`                          | `{}`        | Microphone options (sample rate, echo cancellation, noise suppression, auto gain control). |
| `playerSampleRate`   | `number`                                     | `24000`     | Audio player sample rate.                                                                  |
| `onFunctionCall`     | `(fn) => Promise<string> \| string`          | `undefined` | Handler for agent function call requests.                                                  |
| `onError`            | `(message: AgentErrorMessage) => void`       | `undefined` | Handler for server-reported agent errors.                                                  |
| `onSdkError`         | `(error: Error) => void`                     | `undefined` | Handler for SDK transport errors.                                                          |
| `onWarning`          | `(message: AgentWarningMessage) => void`     | `undefined` | Handler for server-reported agent warnings.                                                |
| `onLatencyReport`    | `(message: LatencyReportMessage) => void`    | `undefined` | Handler for agent latency reports.                                                         |
| `onInjectionRefused` | `(message: InjectionRefusedMessage) => void` | `undefined` | Handler when the server rejects an injected message.                                       |
| `onListenUpdated`    | `(message: ListenUpdatedMessage) => void`    | `undefined` | Handler when the server confirms a `updateListen()` request.                               |
| `onPromptUpdated`    | `(message: PromptUpdatedMessage) => void`    | `undefined` | Handler when the server confirms a `updatePrompt()` request.                               |
| `onSpeakUpdated`     | `(message: SpeakUpdatedMessage) => void`     | `undefined` | Handler when the server confirms a `updateSpeak()` request.                                |
| `onThinkUpdated`     | `(message: ThinkUpdatedMessage) => void`     | `undefined` | Handler when the server confirms a `updateThink()` request.                                |
| `onHistory`          | `(message: HistoryMessage) => void`          | `undefined` | Handler for conversation history received from the server.                                 |

### Return values

| Value               | Type                                                         | Description                                                                                     |
| ------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `state`             | `AgentState`                                                 | Current connection state.                                                                       |
| `mode`              | `AgentMode`                                                  | Current agent mode: `"idle"`, `"listening"`, `"thinking"`, or `"speaking"`.                     |
| `isSpeaking`        | `boolean`                                                    | Whether the agent is speaking.                                                                  |
| `isListening`       | `boolean`                                                    | Whether the agent is listening.                                                                 |
| `isThinking`        | `boolean`                                                    | Whether the agent is preparing a response.                                                      |
| `micActive`         | `boolean`                                                    | Whether the microphone hardware is open.                                                        |
| `micMuted`          | `boolean`                                                    | Whether the microphone is muted.                                                                |
| `outputMuted`       | `boolean`                                                    | Whether agent audio output is muted.                                                            |
| `conversation`      | `ConversationEntry[]`                                        | Conversation history.                                                                           |
| `start`             | `() => Promise<void>`                                        | Connect session and open microphone.                                                            |
| `stop`              | `() => void`                                                 | Disconnect session and close microphone.                                                        |
| `setMicMuted`       | `(muted: boolean) => void`                                   | Mute or unmute the microphone.                                                                  |
| `setOutputMuted`    | `(muted: boolean) => void`                                   | Mute or unmute agent audio.                                                                     |
| `sendUserMessage`   | `(text: string) => void`                                     | Inject a text message as the user.                                                              |
| `sendAgentMessage`  | `(message: string, behavior?: AgentMessageBehavior) => void` | Inject a text message as the agent. `behavior` can be `"default"`, `"queue"`, or `"interrupt"`. |
| `updateListen`      | `(listen: ListenSettings) => void`                           | Update speech-to-text settings during the session.                                              |
| `updateThink`       | `(think: ThinkSettings \| ThinkSettings[]) => void`          | Update LLM settings during the session.                                                         |
| `updateSpeak`       | `(speak: SpeakSettings \| SpeakSettings[]) => void`          | Update text-to-speech settings during the session.                                              |
| `updatePrompt`      | `(prompt: string) => void`                                   | Update the agent system prompt during the session.                                              |
| `clearConversation` | `() => void`                                                 | Clear the local conversation history and request that the session clears its history.           |
| `interrupt`         | `() => void`                                                 | Interrupt agent speech immediately.                                                             |

:::callout{intent="note"}
`useDeepgramAgent` does not support `useAgentClientTool`. Use the provider pattern if you need per-component tool registration.
:::

## Related pages

- [Browser Agent SDK](./self-hosted-deployments-3-browser-agent-overview.md)
- [JavaScript SDK](./self-hosted-deployments-3-browser-agent-javascript.md)
- [React UI Components](./self-hosted-deployments-3-browser-agent-react-ui.md)
- [Widget Embedding Guide](./self-hosted-deployments-3-browser-agent-widget.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.