Agent Insights in LiveKit Cloud
参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ
What（何についてか）
LiveKit Cloudに内蔵されたVoice Agent向けのオブザーバビリティダッシュボード。各Agentセッションについて、文字起こし、トレース、ログ、音声録音を1つの統合タイムライン上で時系列に確認できる。
Why（なぜ必要か）
Voice Agentのデバッグとパフォーマンスチューニングには、パイプライン全体の実行フローを一気通貫で追える必要がある。「ユーザーが何を言い、STTがどう認識し、LLMがどう応答し、TTSがどう再生したか」を別々のログを行き来せずに確認できる。
How（どう動くか）
利用条件
3つの条件を満たす必要がある。いずれかが欠けてもデータは収集されない。
- メディアサーバーがLiveKit Cloudであること（Agent自体は自前インフラでも可、完全self-hostedは不可）
- Cloudダッシュボードの Project Settings > Data and privacy で Agent observability をONにすること
- SDKバージョンが要件を満たすこと（Python 1.3.0以上、Node.js 1.0.18以上、またはAgent Builder）
有効化後は Cloud Dashboard の Sessions > Agent insights タブから確認できる。
統合タイムラインの構成要素
タイムラインは4種類のイベントを時系列に統合表示する。トレースはセッション実行中にリアルタイムでストリーミングされ、文字起こしと音声録音はセッション終了後にアップロードされる。
文字起こし（Transcripts） ユーザーとAgentのターンごとの発話内容。ツール呼び出しやハンドオフもタイムライン上に表示され、トレースやログとの相関が取れる。各イベントにはメタデータとメトリクスが付与される。
セッショントレースとメトリクス（Traces） Voice Pipelineの各ステージ（STT、LLM、TTS等）をspan単位で記録する。各spanにはトークン数、所要時間、Speech identifiers等のメトリクスが付与され、Details パネルで確認できる。パイプラインのボトルネック特定に直結する。
ログ（Logs） Agentサーバーのランタイムログ（ログレベルはサーバー設定に従う）。ただしセッション内のログのみが対象。サーバーのクラッシュ、起動失敗、ディスパッチエラー等のセッション外イベントは含まれない。これらは Log Drains で別途収集する必要がある。
ログの全体像は以下の通り：
| ログの種類 | 収集手段 | 対象 |
|---|---|---|
| Session logs | Insights（自動） | セッション内のランタイムログ |
| Runtime logs（全レプリカ） | Log Drains（sidecar） | stdout/stderr、サーバーレベルイベント |
| Build logs | CLI / Dashboard | ビルド時の出力 |
音声録音（Audio Recordings）
Agentとユーザー両方の音声をローカルで録音し、セッション終了後にCloudへアップロードする。ブラウザ上での再生とダウンロードが可能。ノイズキャンセルが有効な場合、録音されるのはキャンセル適用後の音声（STTやリアルタイムモデルが実際に聞いたもの）であり、デバッグ時に「何を聞いて認識したか」を正確に確認できる。
データ保持（Retention Window）
全オブザーバビリティデータは30日で自動削除される。無料のBuildプランはModel Improvement Programに含まれ、匿名化されたセッションデータが30日を超えて保持される場合がある（Turn Detector等の改善に利用）。有料プラン（Ship / Scale / Enterprise）は対象外で、30日後に完全削除される。
record=False を設定した場合、オブザーバビリティデータのアップロード自体が行われないため、改善プログラムに利用されるデータも存在しないと考えられるが、プライバシーの保証としては明示されていない。
セッションの共有
特定セッションの詳細をLiveKitサポートと共有可能。Ship以上のプランで利用できる。共有リンクはretention period（30日）終了で自動失効し、共有しても保持期間は延長されない。
セッション録音の制御
session.start() の record パラメータでセッションごとに収集内容を制御できる。
| 設定 | 動作 |
|---|---|
record=True（デフォルト） | 全カテゴリ収集 |
record=False | 全カテゴリ収集しない |
| オプションオブジェクト | カテゴリごとに個別制御 |
個別制御のオプションは audio、transcript、traces、logs の4種。省略したキーはデフォルトで True。用途に応じて、本番では全部ON、開発中は音声録音だけOFF、機密セッションでは record=False のように使い分ける。
graph LR S["Agent Session"] -->|"record=True"| U["Upload to Cloud"] U --> T["Transcripts"] U --> R["Traces and Metrics"] U --> L["Session Logs"] U --> A["Audio Recordings"] S -->|"record=False"| N["No Upload"] S -->|"record=obj"| P["Partial Upload"]