livekit-agents

LiveKit Cloud 向け LiveKit Agents 開発

このスキルでは、LiveKit Cloud を使って音声 AI エージェントを開発するための、推奨するガイダンスを提供します。LiveKit Cloud（推奨される方法）の使用を前提としており、API の詳細ではなく、エージェント開発の進め方を示します。API、メソッド、設定に関する事実はすべて、最新のドキュメントで確認してください。

このスキルは LiveKit Cloud の開発者向けです。 LiveKit をセルフホストしている場合、特に LiveKit Inference に関する推奨事項は、そのまま適用できないことがあります。

必須：作業を始める前にこのチェックリストを読む

コードを書く前に、必ず以下のチェックリストを完了してください。

1. このスキルドキュメント全体を読む - MCP を利用できる場合でも、セクションを飛ばさないでください
2. LiveKit Cloud プロジェクトが接続されていることを確認する - 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 キーは不要）
• ノイズキャンセリング、ターン検出など、音声機能を標準搭載
• シンプルな認証情報管理

Cloud プロジェクトに接続する

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. Web 検索を使って 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 は、高度なユースケースに対応しながら低レイテンシを維持する、構造化されたワークフローをサポートしています。

単一構成のエージェントの問題点

会話フロー全体を一つのエージェントが処理すると、次の要素が蓄積していきます。

• あらゆる操作に対応するツール（肥大化したツールリスト）
• あらゆる会話フェーズに対応する指示（肥大化したコンテキスト）
• あらゆる状況に対応する状態管理（複雑化）

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

ハンドオフ：エージェント間の引き継ぎ

ハンドオフを使うと、あるエージェントから別のエージェントへ制御を引き継げます。次の目的でハンドオフを利用してください。

• 異なる会話フェーズを分離する（挨拶 → ヒアリング → 問題解決）
• 専門的な機能を分離する（一般サポート → 請求専門担当）
• コンテキストの境界を管理する（各エージェントが必要なものだけを持つ）

コンテキストを丸ごと引き継ぐのではなく要約できるよう、自然な会話の区切りを基準にハンドオフを設計してください。

タスク：範囲を限定した操作

タスクは、特定の成果を達成するために範囲を厳密に限定したプロンプトです。次の用途でタスクを利用してください。

• エージェントの全機能を必要としない個別の操作
• 汎用エージェントより焦点を絞ったプロンプトが効果的な状況
• 特定の機能だけが必要な場合のコンテキスト削減

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

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

音声エージェントの動作はコードです。エージェントを実装する場合は、必ずテストを含めてください。テストなしでエージェントをリリースすることは、未テストのコードをリリースすることです。

必須のテストワークフロー

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

1. tests/ ディレクトリが存在しない場合は作成します
2. 実装が完了したと判断する前に、少なくとも1つのテストを作成します
3. ユーザーが求めた主要な動作をテストします
4. テストを実行して、合格することを確認します

テスト駆動開発のプロセス

エージェントの動作（指示、ツールの説明、ワークフロー）を変更する場合は、まず期待する動作のテストを作成します：

1. 特定のシナリオでエージェントがどのように動作すべきかを定義します
2. その動作を検証するテストケースを作成します
3. 機能を実装します
4. テストに合格するまで繰り返します

このアプローチにより、「動作しているように見える」ものの、本番環境では失敗するエージェントをリリースせずに済みます。

すべてのエージェントテストで確認すべきこと

最低限、次のテストを作成します：

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

次の点に重点を置いてテストします：

• ツールの呼び出し：エージェントは適切なツールを正しいパラメーターで呼び出しますか？
• 応答の品質：入力に対して適切な応答を生成しますか？
• ワークフローの遷移：引き継ぎやタスクは適切に起動しますか？
• エッジケース：予期しない入力、中断、無音をエージェントはどのように処理しますか？

テスト実装のパターン

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

search: "livekit agents testing"

このフレームワークは次をサポートしています：

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

妥協できない理由

手動テストでは「動作しているように見える」エージェントも、本番環境では頻繁に失敗します：

• プロンプトの変更によって動作が気付かないうちに壊れる
• ツールの説明が、ツールを呼び出すタイミングに影響する
• モデルの更新によって応答パターンが変わる

テストを行えば、ユーザーが問題に気付く前にこれらの問題を検出できます。

テストを省略する場合

ユーザーが明示的にテスト不要と指定した場合は、テストなしで進めます。ただし、次のように伝えてください：

"ご要望に従い、テストなしでエージェントを構築しました。本番環境にデプロイする前に、テストを追加することを強くおすすめします。音声エージェントを手動で検証するのは難しく、テストを行えば気付かないうちに発生するリグレッションを防げます。"

避けるべきよくある間違い

初期エージェントへの機能の詰め込みすぎ

まず「何でもこなす」エージェントを1つ作り、後からツールや指示を追加していくことです。最初の実装がシンプルでも、あらかじめワークフローの構成を設計してください。

問題が起きるまでレイテンシを無視する

レイテンシの問題は積み重なります。開発中に「少し遅い」と感じるエージェントは、実際のネットワーク環境を伴う本番環境では使いものにならなくなります。レイテンシを継続的に測定し、最適化してください。

理解せずにサンプルをコピーする

ドキュメント内のサンプルは、特定のパターンを示すものです。その目的を理解せずにコードをコピーすると、肥大化した構成の悪いエージェントになってしまいます。各コンポーネントを追加する前に、その役割を理解してください。

「プロンプトだけだから」とテストを省略する

エージェントの動作もコードです。プロンプトの変更は、コードの変更と同じように動作に影響します。従来のソフトウェアと同じ厳密さでエージェントの動作をテストしてください。少なくとも1つのテストファイルなしで、エージェントの実装を納品してはいけません。

モデルの知識が最新だと決めつける

重要なルールを改めて強調します。LiveKit API についてモデルの記憶を決して信用しないでください。SDK はモデルのトレーニングサイクルより速く進化します。すべてを検証してください。

ドキュメントを参照するタイミング

次の内容については、必ずドキュメントを参照してください：

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

このスキルでは、次の内容を案内します：

• アーキテクチャのアプローチと設計原則
• ワークフロー構成の判断
• テスト戦略
• 避けるべきよくある落とし穴

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

フィードバックループ

MCP 経由で LiveKit のドキュメントを利用する際は、不足している情報、古くなった情報、分かりにくい内容があれば記録してください。ドキュメントの問題を報告することは、すべての開発者にとってエコシステムの改善につながります。

まとめ

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

1. LiveKit Cloud + LiveKit Inference を基盤として使用する — 本番環境へ最短で移行できます
2. 最新のドキュメントを参照してすべて確認する — モデルの記憶を決して信用しないでください
3. あらゆるアーキテクチャ上の意思決定でレイテンシを最小限に抑える
4. ハンドオフとタスクを使ってワークフローを構成し、複雑さを管理する
5. 変更の前後に動作をテストする — テストなしでリリースしないでください
6. コンテキストは最小限に保つ — 現在のフェーズに必要なものだけを含めてください

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