# @deepgram/browser-agent 中文文档

规范地址：https://npmcn.com/package/%40deepgram/browser-agent/

版本：0\.2\.1
npm 元数据更新时间：2026-09-11T09:54:14.782Z
中文译文更新时间：2026-11-11T20:02:42.832Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40deepgram/browser-agent
原文对照：https://npmcn.com/package/%40deepgram/browser-agent/?lang=original

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

- 包体积（解压后）：35.6 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2025-06-06T19:34:53.786Z
- 最新版本发布：2025-10-06T16:36:22.992Z
- 近 30 天下载量：5599（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 0 个）

## 中文简介

与Deepgram语音代理API兼容的浏览器集成.

## 安装

```sh
npm install @deepgram/browser-agent
```

也可以使用：`pnpm add @deepgram/browser-agent`、`yarn add @deepgram/browser-agent`、`bun add @deepgram/browser-agent`

## README

# 浏览器代理

在浏览器环境中与Deepgram的Voice Agent API相融合的一对实验网络组件.

-   代理组件是一个全能的网络组件,管理麦克风,websocket,以及 动画. 把它添加到任何一页,然后去聊天!
-   Hoop组件是动画,独立. 当你有自己的规则时 更有用 套接字集成,只想要外观和感觉!

## 安装

通过 github 安装到您的软件包中

```json
  "@deepgram/browser-agent": "deepgram/browser-agent#main",
```

## 使用主要组成部分

将库导入到任何地方, 用于注册组件 `deepgram-agent`数字 :

```js
import "@deepgram/browser-agent";
```

那就随你便!

```html
  <body>
    <deepgram-agent
      id="dg-agent"
      url="wss://agent.deepgram.com/v1/agent/converse"
      height="300"
      width="300"
      idle-timeout-ms="10000"
      output-sample-rate="24000"
    ></deepgram-agent>
  </body>
```

然后添加一个 `config` 属性 。 更多见于 属性部分.

### 属性

-   `config` (可选):字符串化的json of a `SettingsConfiguration` 在初始化时发送 API
    -   正在添加或删除 `config` 属性将启动或停止( 分别) WebSocket 连接到 Deepgram API.
    -   因为这个网络组件直接管理用户的麦克风,所以需要用户动作以 尝试连接。 出于这个原因,你最可能想要先使元素 _无_ 一个配置.
    -   为了更好的早期API灵活性,没有验证. 用我们的文件来确保你 配置匹配 .
        -   [设置配置](https://developers.deepgram.com/docs/voice-agent-settings-configuration)
    -   无论何时 `deepgram-agent` 断开连接, 取消配置并等待另一个用户交互 设置并恢复连接.
-   `width` (可选,默认= `"0"`: 代理动画的画布宽度
    -   动画将永远占据一个(粗略的)平方区域,所以这通常应该是一样的 值为 `height`。 。 。 .
-   `height` (可选,默认= `"0"`: 代理动画画布的高度
    -   动画将永远占据一个(粗略的)平方区域,所以这通常应该是一样的 值为 `width`。 。 。 .
-   `auth-scheme` (可选,默认= `"bearer"`: 用您标志使用的认证方案
    -   使用 `bearer` 用于Deepgram API在使用基于符号的认证时。 当地 开发时,您可能会发现使用 API 键更为方便(`token` 计划). **永远不要使用 API 生产浏览器应用程序中的密钥 !**
-   `url` (要求):API url
    -   可能你会安排这个 `"https://api.deepgram.com/v1/agent"`来啊!
-   `idle-timeout-ms` (可选的):在关闭套接字之前等待用户闲置的时间有多长
    -   计时器在用户需要发言时开始(指打开连接时右转, 紧接着 `AgentAudioDone` 活动).
-   `output-sample-rate`: 您想要重播的输出样本率
    -   应该和设置对象的输出率一样。 除非你在尝试 玩得开心点.

### 属性

-   `token` (可选):用于访问 Deepgram / agent API 的符号. 见 [基于符号 认证文件](https://developers.deepgram.com/guides/fundamentals/token-based-authentication) 为了如何 创建安全浏览符 .
    -   如果不提供,则 `auth-scheme` 也会被忽略。 只有当您的 API URL 是 未经认证.

### 活动

作为实验技术 `deepgram-agent` 元素释放出各种事件。 你比较可能 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}会遇到一些比其他的更厉害的人.

#### 共同活动

-   `"no url"`: 试图连接时释放, API URL 缺失
-   `"no config"`: 试图连接和配置缺失时释放
-   `"invalid auth"`: 试图连接时释放, WebSocket 拒绝认证方案或 符号
-   `"socket open"`: 套接字成功打开
-   `"socket close"`: 套接字成功关闭
-   `"connection timeout"`: 套接字由于超时( 10s) 连接失败
-   `"failed to connect user media"`:无法访问用户的麦克风,通常是由于 权限拒绝
-   `"structured message"`从API那里得到了JSON。 这是需要注意的主要事件!
-   `"client message"`向API发送了JSON信息. 用于调试 .

#### 异常事件

-   `"failed setup"`: 发生了一些自定义元素的内部问题
-   `"empty audio"`: 在等待音频数据时收到空消息
-   `"unknown message"`: 从 API 得到一条无效的 JSON 的短信

### 方法

```ts
sendClientMessage(message: ArrayBuffer | string): void {}
```

使用此程序向服务器发送一些(字符串)JSON或二进制数据. 忽略了当 Websocket 是 关闭.

```ts
connect(): Promise<void> {}
```

用它来明确连接 。 倾向于通过设置 `config` 属性.

```ts
disconnect(reason?: string): Promise<void> {}
```

用它来明确断开 最好由你来处理 _删除_ 页:1 `config` 属性.

## 使用 hoop 组件

动画单作为颗粒导入,自动注册为 `deepgram-hoop`数字 :

```js
import "@deepgram/browser-agent/hoop";
```

那就随你便!

```html
  <body>
    <deepgram-hoop
      id="dg-hoop"
      height="300"
      width="300"
      status="active"
    ></deepgram-hoop>
  </body>
```

### 输入音频数据

Hoop组件基于音频信息应用了一定的大小振荡:

-   输出,即代理音频`agent-volume` 属性) 扩展
-   输入,即用户音频(`user-volume` 属性)崩溃

为了缓解焦躁,每个人都在领导者身后画出弧形小径. 您必须提供振幅数据 用户和代理人按框架计算。 见 `sendVolumeUpdates` 函数.

## 捐款

### 先决条件

-   [节点 v18 或 20](https://nodejs.org/en/download/) (虽然我建议通过安装) [数字](https://github.com/nvm-sh/nvm#installing-and-updating)(中文(简体) )

### 本地运行

使用 `npm run vite` 启动 dev 服务器。 你需要设置一个 `DG_API_KEY` 环境变量 命令打开连接.

## 常见问题

### @deepgram/browser-agent 是什么？

与Deepgram语音代理API兼容的浏览器集成\.

### 如何安装 @deepgram/browser-agent？

在项目目录运行 npm install @deepgram/browser-agent，或使用 pnpm add / yarn add / bun add。

### @deepgram/browser-agent 支持 TypeScript 吗？

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

### @deepgram/browser-agent 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @deepgram/browser-agent 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @deepgram/browser-agent 可以商用吗？

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

### @deepgram/browser-agent 的下载量有多少？

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

### @deepgram/browser-agent 还在维护吗？

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