# @deepgram/react 中文文档

规范地址：https://npmcn.com/package/%40deepgram/react/

版本：0\.2\.0
npm 元数据更新时间：2026-09-11T09:54:19.957Z
中文译文更新时间：2026-11-13T05:27:08.763Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deepgram/react
原文对照：https://npmcn.com/package/%40deepgram/react/?lang=original
项目主页：https://github.com/deepgram/react/tree/main/packages/react#readme
源码仓库：https://github.com/deepgram/react

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：171 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2026-04-30T20:28:59.491Z
- 最新版本发布：2026-09-10T15:59:30.972Z
- 近 30 天下载量：2193（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

@ diepgram/ agents 的反应钩和组件

## 安装

```sh
npm install @deepgram/react
```

也可以使用：`pnpm add @deepgram/react`、`yarn add @deepgram/react`、`bun add @deepgram/react`

## README

# @ depgram/ 反应

反应提供者和钩子 [Deepgram 语音代理 API](https://developers.deepgram.com/docs/voice-agent)。管理连接生命周期、麦克风、音频播放、对话状态和模式跟踪.

关于预建的UI组件,见 [`@deepgram/ui`](https://github.com/deepgram/ui)。 。 。 .

## 安装

```bash
npm install @deepgram/react @deepgram/agents
```

## 快速启动

```tsx
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, sendUserMessage } = 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>
  );
}
```

## 代理代理商

将您的组件树与代理状态管理相包。 创建和管理一个 `AgentSession`, (中文(简体) ), `AgentMicrophone`,以及 `AgentPlayer` 内部.

```tsx
<AgentProvider
  config={agentSessionConfig}   // Required: AgentSessionConfig
  microphone={true}             // Enable microphone capture (default: true)
  microphoneOptions={{          // MicrophoneOptions
    sampleRate: 16_000,
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  }}
  tts={true}                    // Enable audio playback (default: true)
  playerSampleRate={24_000}     // Agent audio sample rate (default: 24_000)
  autoStart={false}             // Auto-connect on mount (default: false)
  onFunctionCall={handler}      // Fallback function call handler
  onError={handleError}         // Protocol Error notification
  onSdkError={handleSdkError}   // SDK transport or automatic-start failure
  onWarning={handleWarning}     // Protocol Warning notification
  onLatencyReport={handleLatency}
  onInjectionRefused={handleRefusal}
  onListenUpdated={handleListenUpdate}
  onPromptUpdated={handlePromptUpdate}
  onSpeakUpdated={handleSpeakUpdate}
  onThinkUpdated={handleThinkUpdate}
  onHistory={handleHistory}
>
  {children}
</AgentProvider>
```

`config`, (中文(简体) ), `playerSampleRate`和初始数据 `autoStart` 价值确定提供者一生的资源。 改变这些道具不会重建或自动重启会话. 使用 `updateListen`, (中文(简体) ), `updateThink`, (中文(简体) ), `updateSpeak`,以及 `updatePrompt` 用于支持的会话中间变化; 当需要新的会话配置或玩家样本率时, 重新挂载提供者.

`onListenUpdated`, (中文(简体) ), `onPromptUpdated`, (中文(简体) ), `onSpeakUpdated`,以及 `onThinkUpdated` 获取服务器对匹配运行时间更新方法的确认.

### 模式跟踪

提供者跟踪四种代理模式: `"idle"`, (中文(简体) ), `"listening"`, (中文(简体) ), `"thinking"`,以及 `"speaking"`。 。 。 .

`"thinking"` 仅在服务器发送时设置 `AgentThinking`; 文本输入的转弯可能不会发送该事件. `"speaking"` 当服务器发送时设置 `AgentStartedSpeaking` 以及,何时 `tts={true}`,如果该事件缺席,则从收到的代理音频推断出。 与 `tts={false}`,在进行推断时需要服务器事件。 说话到听觉的过渡是回放意识:当服务器起火时 `AgentAudioDone`,供应商等待到 `AgentPlayer.getRemainingPlaybackTime()` 切换到零前达到零 `"listening"`。这可以防止音频仍在播放时过早改变模式.

## 钩子

### 使用代理状态

连接状态和生命周期控制 .

```ts
const {
  state,          // "idle" | "connecting" | "connected" | "reconnecting" | "disconnected"
  isIdle,         // boolean
  isConnecting,   // boolean
  isConnected,    // boolean
  isReconnecting, // boolean
  isDisconnected, // boolean
  isActive,       // true when connected, connecting, or reconnecting
  start,          // () => Promise<void>; rejects on failure and does not call onSdkError
  stop,           // () => void
} = useAgentState();
```

### 使用代理模式

发言/收听/思考模式.

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

### 代理连接

谈话记录和短信.

```ts
const {
  conversation,       // ConversationEntry[] -- { id, role, content, timestamp }
  clearConversation,  // () => void
  sendUserMessage,    // (text: string) => void
  sendAgentMessage,   // (message: string, behavior?: "default" | "queue" | "interrupt") => void
} = useAgentConversation();
```

### 使用自动麦克风

麦克风状态 哑声控制 和输入量.

```ts
const {
  micActive,       // boolean -- hardware is open
  micMuted,        // boolean -- muted (open but not sending)
  setMicMuted,     // (muted: boolean) => void
  toggle,          // () => void -- toggles mute
  enabled,         // boolean -- false when microphone={false} on provider
  getInputVolume,  // () => number -- 0-1, call per animation frame
} = useAgentMicrophone();
```

### 使用代理服务器

音频回放状态,哑声控制,和输出量.

```ts
const {
  outputMuted,      // boolean
  setOutputMuted,   // (muted: boolean) => void
  toggle,           // () => void
  enabled,          // boolean -- false when tts={false} on provider
  getOutputVolume,  // () => number -- 0-1, call per animation frame
} = useAgentPlayer();
```

### 使用代理控制

生命周期、消息、运行时间设置和哑弹动作组合在一个钩子中。 像其他有重点的钩子一样,会消耗 `AgentContext`,因此,当提供者值变化时,消费者仍然重新屈服.

```ts
const {
  start,
  stop,
  sendUserMessage,
  sendAgentMessage,
  updateListen,
  updateThink,
  updateSpeak,
  updatePrompt,
  clearConversation,
  setMicMuted,
  setOutputMuted,
} = useAgentControls();
```

### 使用代理客户端工具

注册客户端函数调用处理器,范围设定为组件的生命周期. 自动卸载.

```tsx
function WeatherPanel() {
  useAgentClientTool("getWeather", async (fn) => {
    const { city } = JSON.parse(fn.arguments);
    const data = await fetchWeather(city);
    return JSON.stringify(data);
  });

  return <div>...</div>;
}
```

动态客户端工具在 `onFunctionCall` 倒置道具打开 `AgentProvider`。 。 。 .

### 代理会议

直接接触基础 `AgentSession` 实例(逃出舱口).

```ts
const session = useAgentSession();
session.on("warning", (msg) => console.warn(msg));
```

### 使用代理连接

原始上下文值( 逃出舱口) 。 返回全部内容 `AgentContextValue`. 偏好为较小的,目的特定的API表面提供有重点的钩.

### 使用深方程式代理( 独立)

不需要的自带钩 `AgentProvider`。创建和管理自己的会话、麦克风和播放器。 用于简单的集成或者在不需要提供者/文本模式时有用.

初始数据 `config` 财务报告和审定财务报表 `playerSampleRate` 类似地适用于钩子的生平. 使用返回的更新方法来更改所支持的运行时间设置 .

`start()` 开始新会话并清除 `conversation`。 。 。 .

独立的钩子接受相同的通知回调 与 `AgentProvider`,包括: `onListenUpdated`, (中文(简体) ), `onPromptUpdated`, (中文(简体) ), `onSpeakUpdated`,以及 `onThinkUpdated`。 。 。 .

```ts
const {
  state, mode, micActive, micMuted, outputMuted, conversation,
  start, stop, setMicMuted, setOutputMuted,
  sendUserMessage, sendAgentMessage,
  updateListen, updateThink, updateSpeak, updatePrompt,
  clearConversation, interrupt,
} = useDeepgramAgent({
  config: {
    auth: { tokenFactory: () => fetch('/api/token').then(r => r.text()) },
    agent: { think: { provider: { type: 'open_ai', model: 'gpt-4o-mini' } } },
  },
  onWarning: (message) => console.warn(message),
  onLatencyReport: (report) => console.debug(report),
});
```

## 出口

所有钩子、提供者、上下文类型和常见的SDK类型(从 `@deepgram/agents` 为方便起见:

```ts
// Provider
export { AgentProvider };
export type { AgentNotificationCallbacks, AgentProviderProps };

// Hooks
export {
  useAgentState, useAgentMode, useAgentConversation,
  useAgentMicrophone, useAgentPlayer, useAgentControls,
  useAgentClientTool, useAgentSession, useAgentContext,
  useDeepgramAgent,
};

// Hook result types
export type {
  UseAgentStateResult, UseAgentConversationResult,
  UseAgentMicrophoneResult, UseAgentPlayerResult,
  UseAgentModeResult, UseAgentControlsResult,
  UseDeepgramAgentResult, UseDeepgramAgentOptions,
};

// Context types
export type { AgentContextValue, ConversationEntry, AgentMode };

// SDK types (re-exported from @deepgram/agents)
export type {
  AgentSessionConfig, AuthConfig, TokenFactory,
  AgentSettingsObject, AgentMessageBehavior, ListenSettings,
  ThinkSettings, SpeakSettings, MicrophoneOptions,
  AgentThinkingMessage, ListenUpdatedMessage, PromptUpdatedMessage,
  SpeakUpdatedMessage, ThinkUpdatedMessage, LatencyReportMessage,
  HistoryMessage, InjectionRefusedMessage,
  AgentErrorMessage, AgentWarningMessage,
};
```

## 移徙

见 [0.1至0.2 移徙指南](https://github.com/deepgram/react/blob/main/MIGRATION.md) 当升级现有集成时.

## 许可证

麻省理工学院

## 常见问题

### @deepgram/react 是什么？

@ diepgram/ agents 的反应钩和组件

### 如何安装 @deepgram/react？

在项目目录运行 npm install @deepgram/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @deepgram/react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @deepgram/react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @deepgram/react 可以商用吗？

@deepgram/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @deepgram/react 的下载量有多少？

根据 npm 官方下载统计，@deepgram/react 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,193 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deepgram/react 还在维护吗？

最新版本 0\.2\.0 发布于 2026/09/10（2 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/05/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。