livekit-skills

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

このスキルでは、LiveKit Agents SDK を使用して音声 AI エージェントを構築する方法を説明します。LiveKit Cloud とセルフホスト可能なデプロイの両方を扱い、ドキュメントへのアクセスとプロジェクト管理には lk CLI を使用します。API、メソッド、設定に関する事実情報は、すべて最新のドキュメントに基づいている必要があります。

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

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

1. このスキルドキュメント全体を読む — セクションを飛ばさないでください
2. LiveKit の認証情報を設定する（Cloud プロジェクトまたはセルフホストサーバー）— LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET が必要です
3. ドキュメントへのアクセスを設定する — lk CLI をインストールして lk docs コマンドを使用できるようにします
4. テストを作成する計画を立てる — エージェントの実装にはすべてテストを含める必要があります（下記のテストのセクションを参照）
5. すべての API を最新のドキュメントで確認する — LiveKit API について、モデルの記憶に頼らないでください

セットアップ

LiveKit Cloud

LiveKit Cloud は、音声エージェントをすばやく稼働させる方法です。次の機能を提供します。

• マネージドインフラストラクチャ（デプロイするサーバーは不要）
• AI モデル向けの LiveKit Inference（個別の 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 Cloud を使用する場合、AI モデルにアクセスする方法の 1 つとして LiveKit Inference を利用できます。主要な AI モデルプロバイダーを、個別の API キーを必要とせず、LiveKit の認証情報だけで利用できます。

LiveKit Inference の利点：

• AI プロバイダーごとに個別の API キーを管理する必要がありません
• 課金が LiveKit Cloud アカウントに統合されます
• 音声 AI のワークロードに最適化されています

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

セルフホストのセットアップ

セルフホストにすると、デプロイ数と同時実行数に関する Cloud ティアの制限がなくなります。スケーリングを直接管理できます。

ローカル開発

LiveKit サーバーをインストールして実行します。

• macOS：brew install livekit
• Linux：curl -sSL https://get.livekit.io | bash

開発モードで起動します。

livekit-server --dev

デフォルトの認証情報：API キーは devkey、API シークレットは secret です。

環境変数を設定します。

LIVEKIT_URL=ws://localhost:7880
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret

本番環境へのデプロイ

任意のプロバイダー（Hetzner、AWS、GCP など）の Docker、Kubernetes、または VM を使用して livekit-server をデプロイします。詳細は lk docs get-page /home/self-hosting を参照するか、references/self-hosting.md を確認してください。エージェントサーバーは、インフラストラクチャ管理ツールで管理する通常のプロセスとして実行します。

独自のモデルプロバイダーを使用する

セルフホストする場合や、LiveKit Inference ではなく独自の API キーを使用する場合は、環境変数を使用してモデルプロバイダーを直接設定します。

# STT (Speech-to-Text)
DEEPGRAM_API_KEY=your-key

# LLM
OPENAI_API_KEY=your-key

# TTS (Text-to-Speech)
ELEVEN_API_KEY=your-key
# or
CARTESIA_API_KEY=your-key

Agents SDK には、主要なプロバイダー向けのプラグインが用意されています。モデル識別子を直接渡します。

Node.js / TypeScript：

import { voice } from "@livekit/agents";

const session = new voice.AgentSession({
  stt: "deepgram/nova-3:multi",
  llm: "openai/gpt-4.1-mini",
  tts: "cartesia/sonic-3:voice-id",  // or "elevenlabs/..."
});

Python：

session = AgentSession(
    stt="deepgram/nova-3",
    llm="openai/gpt-4.1-mini",
    tts="elevenlabs/...",  # or "cartesia/sonic-3:voice-id"
)

対応プロバイダーの一覧については、lk docs search "plugins" を参照してください。

プロジェクトテンプレート

CLI を使用して、新しいエージェントプロジェクトを初期化します。

バックエンドエージェント：

lk agent init my-agent --template agent-starter-python
lk agent init my-agent --template agent-starter-node

フロントエンドアプリ（React/Next.js、React Native、Swift、Flutter、Android）：

lk agent init my-frontend --template agent-starter-react
lk agent init my-frontend --template agent-starter-react-native

すべてのテンプレートを対話形式で表示するには、--template を省略します。

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

LiveKit Agents は急速に進化している SDK です。モデルのトレーニングデータは、作成された時点ですでに古くなっています。LiveKit を扱う際は、次の点を守ってください。

• 決して推測しないでください：API のシグネチャ、メソッド名、設定オプションを記憶だけに頼らないでください
• 決して当て推量をしないでください：SDK の動作やデフォルト値を推測しないでください
• 必ず確認してください：コードを書く前に、最新のドキュメントを確認してください
• 必ず引用してください：機能を実装する際は、ドキュメントの参照元を示してください

API に自信がある場合でも、このルールを適用してください。必ず確認してください。

ドキュメントの参照には LiveKit CLI を使用してください

LiveKit のコードを書く前に、lk docs CLI コマンドを使用して、最新かつ検証済みの API 情報を確認してください。これにより、古いモデルの知識に頼らずに済みます。

ドキュメントを検索する

lk docs search "voice agent quickstart"
lk docs search "handoffs and tasks"

特定のページを取得する

lk docs get-page /agents/start/voice-ai-quickstart
lk docs get-page /agents/build/tools /agents/build/vision

SDK のソースコードを検索する

lk docs code-search "class AgentSession" --repo livekit/agents
lk docs code-search "@function_tool" --language Python --full-file

変更履歴を確認する

lk docs changelog livekit/agents
lk docs changelog pypi:livekit-agents --releases 5
lk docs changelog npm:livekit-agents --releases 5

CLI がインストールされていない場合

まず LiveKit CLI をインストールしてください。

• macOS：brew install livekit-cli
• Linux：curl -sSL https://get.livekit.io/cli | bash
• Windows：winget install LiveKit.LiveKitCLI

代わりに、このスキルと同じ場所にある references/ ディレクトリ内のリファレンスページを参照できます。

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

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

レイテンシは重要です

音声での会話はリアルタイムです。ユーザーが期待する応答時間は秒単位ではなく、数百ミリ秒以内です。アーキテクチャに関するすべての判断で、レイテンシへの影響を考慮してください。

• 推論時間を短縮するため、LLM のコンテキストサイズを最小限に抑えます
• 会話中に不要なツール呼び出しを避けます
• バッチ応答よりストリーミング応答を優先します
• 想定外の事態（ネットワーク遅延、API タイムアウト）に備えて設計します

コンテキストの肥大化はパフォーマンスを損ないます

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

必要最小限のコンテキストでエージェントを設計してください。

• 現在の会話フェーズに関連するツールだけを含めます
• システムプロンプトを簡潔に保ち、要点を絞ります
• 現在必要とされていないツールやコンテキストを削除します

ユーザーは読みません。聞きます

音声インターフェースには、テキストとは異なる制約があります。

• 長い応答はユーザーを困らせるため、出力を簡潔にします
• ユーザーは前の内容をさかのぼれないため、最初の応答で明確に伝えます
• 割り込みは普通に起こるため、適切に対処できるよう設計します
• 沈黙は故障のように感じられるため、必要に応じて処理中であることを伝えます

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

複雑な音声エージェントは、単一の巨大な構成にするべきではありません。LiveKit Agents は、高度なユースケースに対応しながら低レイテンシを維持する、構造化されたワークフローをサポートしています。

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

会話全体のフローを 1 つのエージェントで処理すると、次のものが蓄積します。

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

その結果、レイテンシが増加し、信頼性が低下します。

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

ハンドオフを使用すると、あるエージェントから別のエージェントへ制御を移せます。次のような場合にハンドオフを使用してください。

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

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

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

タスクは、特定の成果を達成するために設計された、範囲を厳密に限定したプロンプトです。次のような場合にタスクを使用してください。

• エージェントの全機能を必要としない個別の操作
• 汎用エージェントよりも、目的を絞ったプロンプトのほうが適している状況
• 特定の機能だけが必要な場合にコンテキストを削減する

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

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

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

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

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

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

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

エージェントの動作（指示、ツールの説明、ワークフロー）を変更する場合は、望ましい動作のテストを作成することから始めます：

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

この方法により、「一見動作している」ものの、本番環境では失敗するエージェントをリリースするのを防げます。

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

最低限、次の項目をテストしてください：

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

次の点に焦点を当ててテストします：

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

テスト実装のパターン

LiveKit のテストフレームワークを使用してください。現在のパターンについては、lk docs からテストドキュメントを参照してください：

search: "livekit agents testing"

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

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

なぜこれは譲れないのか

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

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

テストにより、ユーザーが気付く前にこうした問題を検出できます。

テストを省略する場合

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

「ご要望どおり、テストなしでエージェントを構築しました。本番環境にデプロイする前に、テストを追加することを強くおすすめします。音声エージェントは手動での検証が難しく、テストによって気付かれないリグレッションを防げます。」

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

最初のエージェントに機能を詰め込みすぎる

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

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

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

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

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

「プロンプトにすぎない」からとテストを省略する

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

モデルの知識が最新だと思い込む

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

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

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

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

このスキルでは、次の内容について説明します。

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

この違いは重要です。このスキルでは、音声エージェントの構築における「考え方」を説明します。ドキュメントでは、具体的な機能の「実装方法」を説明します。

フィードバックループ

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

まとめ

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

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

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