React Hooks & Provider

1
import {
2
  AgentProvider,
3
  useAgentState,
4
  useAgentConversation,
5
  useAgentMode,
6
} from "@deepgram/react";
7
8
function App() {
9
  return (
10
    <AgentProvider
11
      config={{
12
        auth: { tokenFactory: () => fetch("/api/token").then((r) => r.text()) },
13
        agent: "YOUR_AGENT_ID",
14
      }}
15
    >
16
      <VoiceAgent />
17
    </AgentProvider>
18
  );
19
}
20
21
function VoiceAgent() {
22
  const { state, start, stop } = useAgentState();
23
  const { conversation } = useAgentConversation();
24
  const { mode } = useAgentMode();
25
26
  return (
27
    <div>
28
      <p>Mode: {mode}</p>
29
      <button onClick={() => (state === "connected" ? stop() : start())}>
30
        {state === "connected" ? "Disconnect" : "Connect"}
31
      </button>
32
      <ul>
33
        {conversation.map((msg) => (
34
          <li key={msg.id}>
35
            <strong>{msg.role}:</strong> {msg.content}
36
          </li>
37
        ))}
38
      </ul>
39
    </div>
40
  );
41
}

1
<AgentProvider
2
  config={agentSessionConfig}
3
  microphone={true}
4
  microphoneOptions={{ vad: true }}
5
  tts={true}
6
  playerSampleRate={24_000}
7
  autoStart={false}
8
  onFunctionCall={handleFunctionCall}
9
>
10
  {children}
11
</AgentProvider>

1
const {
2
  state,           // "idle" | "connecting" | "connected" | "reconnecting" | "disconnected"
3
  isIdle,          // true when state === "idle"
4
  isConnecting,    // true when state === "connecting"
5
  isConnected,     // true when state === "connected"
6
  isReconnecting,  // true when state === "reconnecting"
7
  isDisconnected,  // true when state === "disconnected"
8
  isActive,        // true when connected, connecting, or reconnecting
9
  start,           // () => Promise<void> — connect session + open mic
10
  stop,            // () => void — disconnect + close mic
11
} = useAgentState();

1
const {
2
  conversation,       // ConversationEntry[]
3
  clearConversation,  // () => void
4
  sendUserMessage,    // (text: string) => void — inject a text message as the user
5
} = useAgentConversation();

1
const {
2
  mode,        // "idle" | "listening" | "speaking"
3
  isSpeaking,  // true when mode === "speaking"
4
  isListening, // true when mode === "listening"
5
} = useAgentMode();

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

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

1
const {
2
  start,              // () => Promise<void>
3
  stop,               // () => void
4
  sendUserMessage,    // (text: string) => void
5
  clearConversation,  // () => void
6
  setMicMuted,        // (muted: boolean) => void
7
  setOutputMuted,     // (muted: boolean) => void
8
} = useAgentControls();

1
// Safe in effects — stable refs mean no re-runs
2
useEffect(() => {
3
  const handleKey = (e: KeyboardEvent) => {
4
    if (e.key === "m") setMicMuted((prev) => !prev);
5
  };
6
  window.addEventListener("keydown", handleKey);
7
  return () => window.removeEventListener("keydown", handleKey);
8
}, [setMicMuted]); // setMicMuted identity never changes

1
useAgentClientTool(
2
  name: string,
3
  handler: (fn: FunctionCallItem) => Promise<string> | string
4
): void

1
function WeatherWidget() {
2
  const [weather, setWeather] = useState(null);
3
4
  useAgentClientTool("get_weather", async (fn) => {
5
    const { city } = JSON.parse(fn.input);
6
    const data = await fetchWeather(city);
7
    setWeather(data);
8
    return JSON.stringify(data);
9
  });
10
11
  return weather ? <WeatherCard data={weather} /> : null;
12
}

1
function MapComponent() {
2
  const [location, setLocation] = useState({ lat: 0, lng: 0 });
3
4
  // Always reads the current location value
5
  useAgentClientTool("getLocation", () => {
6
    return JSON.stringify(location);
7
  });
8
9
  useAgentClientTool("setLocation", (fn) => {
10
    const coords = JSON.parse(fn.input);
11
    setLocation(coords);
12
    return JSON.stringify({ ok: true });
13
  });
14
15
  return <Map center={location} />;
16
}

1
const session = useAgentSession();
2
3
useEffect(() => {
4
  const handler = (msg) => console.log("Agent thinking:", msg);
5
  session.on("agent-thinking", handler);
6
  return () => session.off("agent-thinking", handler);
7
}, [session]);

1
const ctx = useAgentContext();
2
// ctx.state, ctx.mode, ctx.conversation, ctx.micMuted, etc.

1
import { useDeepgramAgent } from "@deepgram/react";
2
3
function VoiceAgent() {
4
  const {
5
    state,
6
    conversation,
7
    micActive,
8
    outputMuted,
9
    start,
10
    stop,
11
    setMicMuted,
12
    setOutputMuted,
13
    sendUserMessage,
14
    interrupt,
15
  } = useDeepgramAgent({
16
    config: {
17
      auth: { tokenFactory: () => fetch("/api/token").then((r) => r.text()) },
18
      agent: "YOUR_AGENT_ID",
19
    },
20
    micOptions: { vad: true },
21
    playerSampleRate: 24_000,
22
    onFunctionCall: async (fn) => {
23
      return JSON.stringify({ result: "ok" });
24
    },
25
  });
26
27
  return (
28
    <div>
29
      <button onClick={() => (state === "connected" ? stop() : start())}>
30
        {state === "connected" ? "Disconnect" : "Start"}
31
      </button>
32
      <ul>
33
        {conversation.map((msg) => (
34
          <li key={msg.id}>
35
            <strong>{msg.role}:</strong> {msg.content}
36
          </li>
37
        ))}
38
      </ul>
39
    </div>
40
  );
41
}