deepgram-js-voice-agent

使用 Deepgram Voice Agent（JavaScript / TypeScript SDK）

通过 wss://agent.deepgram.com/v1/agent/converse 运行全双工语音 Agent：输入音频、LLM 编排、输出音频，以及函数调用和提示词／运行时更新。

何时使用此产品

• 你需要交互式语音助手，用户说话后，Agent 进行思考并以语音回应。
• 你需要在对话循环中进行函数／工具调用。
• 你希望由 Deepgram 托管 STT + 思考 + TTS 编排。

以下情况请使用其他技能：

• 你只需要转录 → deepgram-js-speech-to-text 或 deepgram-js-conversational-stt。
• 你只需要语音合成 → deepgram-js-text-to-speech。
• 你需要项目密钥、用量、模型或其他管理 API → deepgram-js-management-api。

身份验证

require("dotenv").config();

const { DeepgramClient, DeepgramEnvironment } = require("@deepgram/sdk");

const deepgramClient = new DeepgramClient({
  apiKey: process.env.DEEPGRAM_API_KEY,
  environment: DeepgramEnvironment.Agent,
});

WebSocket 本身通过 src/CustomClient.ts 路由到 Agent 主机，但仓库示例使用 DeepgramEnvironment.Agent，因此 client.agent.v1.settings.think.models.list() 也会指向 Agent 基础地址。

快速开始

摘自 examples/09-voice-agent.ts：

const deepgramConnection = await deepgramClient.agent.v1.createConnection();

deepgramConnection.on("message", (data) => {
  if (data.type === "ConversationText") {
    console.log("Conversation text:", data);
  } else if (typeof data === "string") {
    console.log("Audio received (length):", data.length);
  }
});

deepgramConnection.connect();
await deepgramConnection.waitForOpen();

deepgramConnection.sendSettings({
  type: "Settings",
  audio: {
    input: { encoding: "linear16", sample_rate: 24000 },
    output: { encoding: "linear16", sample_rate: 16000, container: "wav" },
  },
  agent: {
    language: "en",
    listen: { provider: { type: "deepgram", version: "v1", model: "nova-3" } },
    think: {
      provider: { type: "open_ai", model: "gpt-4o-mini" },
      prompt: "You are a friendly AI assistant.",
    },
    speak: { provider: { type: "deepgram", model: "aura-2-thalia-en" } },
    greeting: "Hello! How can I help you today?",
  },
});

同一示例还展示了如何使用 client.agent.v1.settings.think.models.list() 查找受支持的思考模型。

关键参数／API 接口

• 连接设置：client.agent.v1.createConnection() / connect()。
• 首条出站控制消息：sendSettings(AgentV1Settings)。
• 运行时更新：sendUpdatePrompt(...)、sendUpdateThink(...)、sendUpdateSpeak(...)、sendInjectUserMessage(...)、sendInjectAgentMessage(...)、sendFunctionCallResponse(...)、sendKeepAlive(...)、sendMedia(...)。
• src/api/resources/agent/resources/v1/client/Socket.ts 中的重要入站事件：Welcome、SettingsApplied、ConversationText、UserStartedSpeaking、AgentThinking、FunctionCallRequest、AgentStartedSpeaking、AgentAudioDone、Warning、Error，以及音频负载。

限制

此 SDK 提供实时 Agent 运行时以及 settings.think.models.list()，但当前生成的接口中不提供持久化 Voice Agent 配置的 CRUD 端点。

API 参考（分层）

1. 仓库内参考资料：reference.md → Agent V1 Settings Think Models；实时 WebSocket 行为由 src/CustomClient.ts 和 src/api/resources/agent/resources/v1/client/{Client,Socket}.ts 定义。
2. 规范 OpenAPI（REST）：https://developers.deepgram.com/openapi.yaml
3. 规范 AsyncAPI（WSS）：https://developers.deepgram.com/asyncapi.yaml
4. Context7：库 ID /llmstxt/developers_deepgram_llms_txt
5. 产品文档：
   • https://developers.deepgram.com/reference/voice-agent/voice-agent
   • https://developers.deepgram.com/docs/voice-agent
   • https://developers.deepgram.com/docs/configure-voice-agent
   • https://developers.deepgram.com/docs/voice-agent-message-flow

注意事项

1. 设置必须是首条消息。 套接字打开后，立即发送 sendSettings({ type: "Settings", ... })。
2. 音频和 JSON 事件共用同一消息流。 你的 message 处理程序必须根据 typeof data 和 data.type 进行分流。
3. Keepalive 很重要。 examples/09-voice-agent.ts 每隔 5 秒发送一次 KeepAlive，以维持长会话。
4. 两端的编码和采样率必须一致。 不匹配会导致上传音频失真或播放无法使用。
5. 思考模型发现与 WebSocket 分开。 选择提供商前，请使用 client.agent.v1.settings.think.models.list()。
6. 函数调用请求以数组形式到达。 检查 data.functions[]，然后使用 sendFunctionCallResponse({ type: "FunctionCallResponse", id, name, content }) 回复。
7. 此 SDK 目前不支持持久化 Agent 配置。 如果需要存储配置，请使用原始 HTTP 或其他 SDK 接口。

此仓库中的示例文件

• examples/09-voice-agent.ts
• examples/34-agent-custom-providers.ts
• examples/35-agent-provider-combinations.ts
• examples/36-agent-inject-message.ts

核心产品技能

如需跨语言的 Deepgram 产品知识——整合的 API 参考、文档查找工具、精简且可运行的示例、第三方集成示例和 MCP 设置，请安装核心技能：

npx skills add deepgram/skills

此 SDK 提供符合各语言习惯的代码技能；deepgram/skills 提供跨语言的产品知识（参见 api、docs、recipes、examples、starters、setup-mcp）。