mcpField
D
deepgram-js-voice-agent

deepgram-js-voice-agent

github.com/deepgramエージェントワークフロー27753 回インストール今日更新
リポジトリ

deepgram-js-voice-agent について

Deepgramでリアルタイム音声エージェントを構築するためのJavaScript／TypeScript SDKスキルです。双方向音声、会話イベント、関数呼び出し、実行中の更新を扱います。

主な機能

  1. 01双方向リアルタイム音声接続
  2. 02音声と会話イベントの処理
  3. 03関数呼び出しの処理
  4. 04プロンプトと設定の実行中更新
  5. 05thinkモデルの検索

活用シーン

  1. 01音声対話アシスタントの構築
  2. 02音声セッション中のツール呼び出し
  3. 03実行中のプロンプトや音声設定の変更

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/deepgram/deepgram-js-sdk --skill deepgram-js-voice-agent

インストール後、Claude Code で/deepgram-js-voice-agentを入力して読み込まれたか確認します。

詳細

Deepgram Voice Agent の使用（JavaScript / TypeScript SDK）

wss://agent.deepgram.com/v1/agent/converse を介した全二重音声エージェントランタイムです。音声入力、LLM のオーケストレーション、音声出力に加え、関数呼び出しやプロンプト／ランタイムの更新に対応しています。

この製品を使用する場面

  • ユーザーが話し、エージェントが考え、音声で応答する対話型音声アシスタントが必要な場合。
  • 会話のループ内で関数／ツール呼び出しが必要な場合。
  • STT、思考、TTS のオーケストレーションを Deepgram にホストさせたい場合。

次の場合は、別のスキルを使用してください：

  • 文字起こしのみが必要な場合 → 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 によってエージェントホストにルーティングされますが、リポジトリのサンプルでは DeepgramEnvironment.Agent を使用しているため、client.agent.v1.settings.think.models.list() もエージェントのベース URL を参照します。

クイックスタート

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 では、ライブエージェントランタイムと settings.think.models.list() を利用できますが、現在の生成済み API サーフェスでは、永続化された 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. 製品ドキュメント：

注意点

  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 では永続化されたエージェント設定を利用できません。 保存済みの設定が必要な場合は、raw 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 を参照）が含まれています。

コメント

Markdown 対応