LiveKit Cloud での音声エージェント開発

このスキルは、LiveKit Cloud を使用して音声 AI エージェントを構築するための意見的なガイダンスを提供します。このスキルは LiveKit Cloud（推奨されるパス）を使用していることを前提とし、エージェント開発への アプローチ方法 を示しています。API 仕様ではなく、すべての事実情報は最新のドキュメントから取得する必要があります。

このスキルは LiveKit Cloud 開発者向けです。 自身で LiveKit をホストしている場合、いくつかの推奨事項（特に LiveKit Inference 周辺）は直接適用されない可能性があります。

必読：開始前にこのチェックリストを確認してください

コードを書く前に、このチェックリストを完了してください：

1. このスキルドキュメント全体を読んでください - MCP が利用可能でもセクションをスキップしないでください
2. LiveKit Cloud プロジェクトが接続されていることを確認してください - クラウドプロジェクトから LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET が必要です
3. ドキュメントアクセスをセットアップしてください - MCP が利用可能な場合は使用し、そうでない場合はウェブ検索を使用してください
4. テスト作成を計画してください - すべてのエージェント実装にはテストが必須です（下記のテストセクションを参照）
5. すべての API を最新ドキュメントで確認してください - LiveKit API について、モデルの記憶に依存しないでください

このチェックリストは MCP が利用可能かどうかに関わらず適用されます。MCP はドキュメントアクセスを提供しますが、このスキルのガイダンスに 代わるものではありません。

LiveKit Cloud セットアップ

LiveKit Cloud は、音声エージェントを実行する最速の方法です。以下を提供します：

• マネージド インフラストラクチャ（デプロイするサーバーなし）
• LiveKit Inference による AI モデル（別の API キーは不要）
• 組み込みのノイズキャンセレーション、ターン検出、その他の音声機能
• シンプルな認証情報管理

クラウドプロジェクトに接続する

1. まだサインアップしていない場合は、cloud.livekit.io でサインアップしてください

2. プロジェクトを作成します（または既存のものを使用）

3. プロジェクト設定から認証情報を取得します：

   • LIVEKIT_URL - プロジェクトの WebSocket URL（例：wss://your-project.livekit.cloud）
   • LIVEKIT_API_KEY - 認証用の API キー
   • LIVEKIT_API_SECRET - 認証用の API シークレット

4. これらを環境変数として設定します（通常は .env.local に）：

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret

LiveKit CLI は認証情報のセットアップを自動化できます。現在のコマンドについては CLI ドキュメントを参照してください。

AI モデルに LiveKit Inference を使用する

LiveKit Inference は、LiveKit Cloud で AI モデルを使用するための推奨される方法です。 別の API キーを必要とせず、すべて LiveKit 認証情報を使用して主要な AI モデルプロバイダーへのアクセスを提供します。

LiveKit Inference のメリット：

• 各 AI プロバイダーの個別の API キー管理が不要
• 課金が LiveKit Cloud アカウントを通じて統合される
• 音声 AI ワークロード向けに最適化

利用可能なモデル、サポートされているプロバイダー、および現在の使用パターンについては、ドキュメントを参照してください。ドキュメントには常に最新の情報が記載されています。

重要なルール：LiveKit API についてモデルの記憶を信頼しないでください

LiveKit Agents は急速に進化する SDK です。モデルの訓練データは作成された瞬間から古くなります。LiveKit を使用する場合：

• API シグネチャ、メソッド名、設定オプションをメモリから 推測しないでください
• SDK の動作やデフォルト値を 推測しないでください
• コード を書く前に、常に最新ドキュメントで 確認してください
• 機能を実装する際は、常にドキュメントのソースを 明記してください

このルールは API に確信がある場合でも適用されます。いずれにせよ確認してください。

必須：ドキュメント用に LiveKit MCP サーバーを使用する

LiveKit コードを書く前に、LiveKit ドキュメント MCP サーバーへのアクセスを確保してください。これにより、最新の検証済み API 情報が提供され、古いモデル知識への依存が防止されます。

MCP の利用可能性を確認する

livekit-docs MCP ツールを探してください。利用可能な場合は、すべてのドキュメントルックアップに使用してください：

• 機能を実装する前にドキュメントを検索する
• API シグネチャとメソッドパラメータを確認する
• 設定オプションとその有効な値を検索する
• 特定のタスク用の実際に動作する例を見つける

MCP が利用不可の場合

LiveKit MCP サーバーが設定されていない場合は、ユーザーに通知し、インストールを推奨してください。サポートされているすべてのプラットフォームのインストール手順は、以下で入手できます：

https://docs.livekit.io/intro/mcp-server/

ユーザーのコーディングエージェント用の適切なインストール手順をそのページから取得してください。

MCP が利用不可な場合のフォールバック

現在のセッションで MCP をインストールできない場合：

1. ドキュメントをリアルタイムで検証できないことをユーザーに直ちに通知してください
2. ウェブ検索を使用して、docs.livekit.io から最新ドキュメントを取得する
3. すべての LiveKit 固有のコード に # UNVERIFIED: Please check docs.livekit.io for current API のようなコメントで明示的にマークしてください
4. 確認できないことを明確に述べてください：「このAPI シグネチャを最新ドキュメントに対して確認できません」
5. ユーザーにコードを使用する前に https://docs.livekit.io で確認することを推奨してください

音声エージェント アーキテクチャの原則

音声 AI エージェントは、テキストベースのエージェントや従来のソフトウェアとは根本的に異なる要件があります。これらの原則を習得してください：

レイテンシーは重要です

音声会話はリアルタイムです。ユーザーは秒単位ではなく、数百ミリ秒以内の応答を期待しています。すべてのアーキテクチャ決定では、レイテンシーへの影響を考慮する必要があります：

• LLM コンテキストサイズを最小化して推論時間を削減する
• アクティブな会話中の不要なツール呼び出しを回避する
• バッチ応答ではなくストリーミング応答を優先する
• 不幸なパス（ネットワーク遅延、API タイムアウト）用に設計する

コンテキストの膨張がパフォーマンスを損なう

大きなシステムプロンプトと広範なツールリストは、直接レイテンシーを増加させます。50 個のツールと 10,000 トークンのシステムプロンプトを持つ音声エージェントは、モデルの速度に関わらず遅く感じられます。

最小限の実行可能なコンテキストでエージェントを設計してください：

• 現在の会話フェーズに関連するツールのみを含める
• システムプロンプトをシンプルで簡潔に保つ
• アクティブに必要とされていないツールとコンテキストを削除する

ユーザーは読まない、聞く

音声インターフェースの制約は、テキストと異なります：

• 長い応答はユーザーをイライラさせます — 出力は簡潔に保つ
• ユーザーはスクロールバックできません — 初回配信で明確さを保証する
• 割り込みは通常です — 優雅な処理用に設計する
• 沈黙は壊れて見えます — 処理中に確認応答する

ワークフロー アーキテクチャ：ハンドオフとタスク

複雑な音声エージェントはモノリシックであるべきではありません。LiveKit Agents は、低レイテンシーを維持しながら洗練されたユースケースを処理する構造化ワークフローをサポートします。

モノリシック エージェントの問題

単一のエージェントが会話フロー全体を処理する場合、以下が蓄積されます：

• あらゆる可能なアクション用のツール（ツールリストの膨張）
• あらゆる会話フェーズの指示（コンテキストの膨張）
• すべてのシナリオの状態管理（複雑さ）

これにより、レイテンシーが増加し、信頼性が低下します。

ハンドオフ：エージェント間の遷移

ハンドオフにより、1 つのエージェントが別のエージェントに制御を転送できます。ハンドオフを使用して：

• 異なる会話フェーズを分離する（挨拶 → 受け入れ → 解決）
• 専門化された機能を分離する（一般的なサポート → 請求スペシャリスト）
• コンテキスト境界を管理する（各エージェントは必要なものだけを持つ）

コンテキストを一括転送するのではなく、要約できる自然な会話境界の周りにハンドオフを設計してください。

タスク：スコープ化された操作

タスクは、特定の成果を達成するために設計された厳密にスコープ化されたプロンプトです。タスクを使用して：

• エージェント全機能を必要としない個別操作
• フォーカスされたプロンプトが汎用エージェントより優れたパフォーマンスを発揮する状況
• 特定の機能のみが必要な場合のコンテキスト削減

ハンドオフとタスクの実装詳細については、ドキュメントを参照してください。

必須：エージェント動作のテストを作成する

音声エージェントの動作はコードです。すべてのエージェント実装にはテストが必須です。テストなしでエージェントをリリースすることは、テストされていないコードをリリースすることです。

必須テストワークフロー

LiveKit エージェントを構築または変更する場合：

1. テストディレクトリを作成します - 存在しない場合は tests/ を作成
2. 少なくとも 1 つのテストを書きます - 実装を完了したと見なす前に
3. コア動作をテストします - ユーザーが要求した内容
4. テストを実行します - テストが成功することを確認

テスト駆動開発プロセス

エージェントの動作を変更する場合 — 指示、ツール記述、ワークフロー — 目的の動作のテストを作成することで開始してください：

1. 特定のシナリオでエージェントが何をすべきかを定義する
2. この動作を検証するテストケースを作成する
3. 機能を実装する
4. テストが成功するまで反復する

このアプローチにより、「機能しているように見える」が本番環境で失敗するエージェントのリリースが防止されます。

すべてのエージェント テストが対象とすべき事項

最低でも、以下のテストを作成してください：

• 基本的な会話フロー：エージェントは挨拶に適切に応答する
• ツール呼び出し（ツールが存在する場合）：ツールが正しいパラメータで呼び出される
• エラー処理：エージェントが予期しない入力を適切に処理する

テストに焦点を当てる：

• ツール呼び出し：エージェントは正しいツールを正しいパラメータで呼び出しますか？
• 応答品質：エージェントは特定の入力に対して適切な応答を生成しますか？
• ワークフロー遷移：ハンドオフとタスクは正しくトリガーされますか？
• エッジケース：エージェントは予期しない入力、割り込み、沈黙にどのように対応しますか？

テスト実装パターン

LiveKit のテストフレームワークを使用してください。MCP 経由でテストドキュメントを参照して現在のパターンを確認してください：

search: "livekit agents testing"

フレームワークは以下をサポートしています：

• シミュレートされたユーザー入力
• エージェント応答の検証
• ツール呼び出しアサーション
• ワークフロー遷移テスト

これが譲歩不可である理由

「機能しているように見える」エージェントは本番環境で頻繁に失敗します：

• プロンプト変更は動作をサイレントに破壊する
• ツール記述はツールが呼び出される時期に影響する
• モデル更新は応答パターンを変更する

テストはこれらの問題をユーザーが発見する前に検出します。

テストをスキップする

ユーザーが明示的にテストなしをリクエストした場合、その通りに進みますが、次の旨を通知してください：

「リクエストどおり、テストなしでエージェントを構築しました。本番環境にデプロイする前にテストを追加することを強くお勧めします。音声エージェントは手動で検証が難しく、テストはサイレント リグレッションを防止します。」

避けるべき一般的な間違い

初期エージェントのオーバーロード

「すべてを行う」単一のエージェントから始めて、時間をかけてツール/指示を追加していく。代わりに、初期実装がシンプルでも、ワークフロー構造を事前に設計してください。

レイテンシーが問題になるまで無視する

レイテンシーの問題は複合します。開発で「少し遅い」と感じるエージェントは、実際のネットワーク条件の本番環境では使用不可になります。継続的にレイテンシーを測定および最適化してください。

理解なしに例をコピーする

ドキュメント内の例は、特定のパターンを示しています。目的を理解せずにコードをコピーすると、膨張して不十分に構造化されたエージェントになります。含める前に、各コンポーネントが何をするかを理解してください。

「プロンプトだけだから」テストをスキップする

エージェント動作はコードです。プロンプト変更はコード変更と同じくらい動作に影響します。従来のソフトウェアと同じ厳密さでエージェント動作をテストしてください。テストファイルなしでエージェント実装を配信しないでください。

モデル知識が最新だと仮定する

重要なルールを繰り返します：LiveKit API についてモデルメモリを信頼しないでください。SDK は モデル訓練サイクルより速く進化します。すべてを確認してください。

ドキュメントを参照する時期

常にドキュメントを参照してください：

• API メソッド シグネチャとパラメータ
• 設定オプションと有効な値
• SDK バージョン固有の機能または変更
• デプロイとインフラストラクチャ セットアップ
• モデル プロバイダー統合詳細
• CLI コマンドとフラグ

このスキルは以下のガイダンスを提供します：

• アーキテクチャ アプローチと設計原則
• ワークフロー構造の決定
• テスト戦略
• 一般的な落とし穴を避ける方法

区別は重要です：このスキルは音声エージェント構築について どう考えるか を説明します。ドキュメントは、特定の機能を どのように実装するか を説明します。

フィードバック ループ

MCP 経由で LiveKit ドキュメントを使用する場合は、ギャップ、古い情報、または紛らわしいコンテンツに注意してください。ドキュメント上の問題をレポートすると、すべての開発者がエコシステムを改善するのに役立ちます。

概要

LiveKit Cloud で効果的な音声エージェントを構築するには、以下が必要です：

1. LiveKit Cloud + LiveKit Inference を基盤として使用します — 本番環境への最速パスです
2. すべてを検証します — 最新ドキュメントに対して — モデルの記憶を信頼しないでください
3. すべてのアーキテクチャ決定でレイテンシーを最小化します
4. ハンドオフとタスクを使用してワークフローを構造化します — 複雑さを管理するため
5. 変更前後で動作をテストします — テストなしでリリースしないでください
6. コンテキストを最小限に保ちます — 現在のフェーズに必要なものだけを含める

これらの原則は SDK バージョンまたは API 変更に関わらず有効です。すべての実装仕様については、MCP 経由で LiveKit ドキュメントを参照してください。