running-livekit-simulations

LiveKit シミュレーションの実行

シミュレーションでは、LLM 駆動のシミュレートされたユーザーを使って実際のエージェントにシナリオを実行し、その後、判定役がトランスクリプトを評価します。ユニットテストでは、1 回のターンについてアサーションします。シミュレーションでは、会話全体が適切な結果に到達したかを確認できます。

実行前に lk agent simulate --help を読んでください。サブコマンドやフラグは変更されるため、誤ったフラグを指定すると有料の実行を無駄にしてしまいます。このスキルではそれらを再掲しません。残りの情報は reading-livekit-docs にあります。

シミュレーションを使う場面

本番環境にデプロイする前に、長期的な動作をリグレッションテストするにはシミュレーションを使います。たとえば、発信者が話を戻した場合に複数ターンの会話が適切な結果に到達するか、早い段階で集めた詳細情報が最後まで保持されるか、プレッシャーを受けてもエージェントが指示に従うか、そして適切な状態で終了したかを確認できます。1 回のターンを確認する場合は testing-livekit-agents を使い、編集中に動作を試す場合は debugging-livekit-agents を使ってください。

実行

エージェントのプロジェクトディレクトリから実行してください。モードはサブコマンドです。

lk agent simulate text --scenarios scenarios.yaml    # see --help for the current flags

シナリオファイルを指定しない場合、CLI はエージェントのソースからシナリオを生成します。その際、コードがアップロードされ、CLI は最初に確認を求めます。シナリオの生成については writing-livekit-scenarios を参照してください。

デフォルトでは、CLI はエージェントをローカルワーカーとして起動し、シナリオを実行し、実行終了時に停止します。オプションを使うと、名前を指定して、すでに実行中のエージェントを評価できます。その場合、生成元となるローカルソースがないため、シナリオファイルが必要です。

同時実行数には、1 回の実行ごと、およびプロジェクトごとに上限があります。現在の上限はドキュメントで確認してください。

テキストまたは音声

デフォルトはテキストで、こちらが適切な選択です。 シミュレートされたユーザーはエージェントとテキストでやり取りするため、フレームワークが STT、TTS、VAD を無効にする一方で、LLM、ツール、会話ロジックをテストできます。高速で、低コストかつ、より決定論的です。反復的な開発や自動実行には、テキストを使ってください。

音声では、同じシナリオを完全な音声パイプラインで実行します。 シミュレートされたユーザーは発信者と同じように話し、聞き、割り込みます。音声でしか分からない次の点を評価できます。

• ターンテイキング：発信者が話し終わる前に話し始めること、または話し終わった発信者を待たせること。
• 割り込みへの対応：割り込みに応じて発話を譲ること、そして短い相づちと新しいターンを区別すること。
• 双方向の文字起こし精度。重要な項目である名前、数字、住所、確認コードを個別に評価します。
• 体感レイテンシ：発信者が実際に聞いた内容です。エージェントが自身について報告する内容とは異なり、この差がユーザーの体験になります。

音声実行はリアルタイムで行われ、ターンごとに STT と TTS のプロバイダーを呼び出すため、より高い料金が発生します。リリース候補や、音声、ターンテイキング、割り込みに関わる変更の確認に使ってください。定期ジョブには含めないでください。

音声サブコマンドには、シミュレートされた発信者の音声を劣化させるオプション（ノイズ、性能の低いマイク、パケットロス）があります。聞き取りにくい音声に対してエージェントがどう対応するかをテストするために使ってください。推測せず、聞き返すべきです。最悪の条件の発信者を想定するには、これらを組み合わせてください。

リリース前の実行を自動化する

コミット済みのシナリオファイルと、スケジュール実行またはリリースブランチのジョブがあれば十分です。CLI はターミナルに接続されていない場合にプレーンテキストで出力し、いずれかのシナリオが失敗するとゼロ以外の終了コードを返すため、追加の設定なしでジョブが失敗します。ドキュメントには、出発点として使える CI の具体例があります。自動実行はテキストモードにしてください。コミット済みファイル内のすべてのシナリオに合格する必要があり、1 つでも失敗するとジョブ全体が失敗します。そのため、まだエージェントが合格できない意欲的なシナリオは、必要に応じて実行する別ファイルに分けてください。

結果を読む

実行すると、シナリオごとの判定とダッシュボードへのリンクが表示されます。判定は何が起きたかを示し、トランスクリプトはその理由を示すため、トランスクリプトから確認してください。ダッシュボードへのリンクは人間向けです。実行結果を確認するには export を使います。各シナリオのチャットコンテキスト全体を含む、完了した実行結果を JSON として出力します。そこから失敗したトランスクリプトを読んだり、2 つの実行結果を比較したり、ビルド成果物として実行結果をアーカイブしたりできます。list は実行 ID を検索し、機械可読形式でも出力します。フラグの名前は --help で確認できます。

失敗をトリアージするには、次のどれに当てはまるかを判断してください。

1. エージェントのバグです。 エージェントを修正して、再実行してください。まず指示とツールの説明を確認してください。推論の誤りに見える失敗は、多くの場合、いつ使うべきかが説明に記載されていないツールが原因です。
2. シナリオの不備です。 期待される動作がエージェントにすべきでないことを要求しているか、判定者が一貫して判断できないほど曖昧です。シナリオを修正してください。判定結果が実行ごとに変わる最も一般的な原因は、曖昧な agent_expectations です。
3. シミュレーション環境の不備です。 シナリオでは成功するのに本番環境では失敗する、またはその逆です。通常は、エージェントが異なるデータにたどり着いたか、派生した指示から問題の原因となったターンが抜けているか、音声でのみ発生するためテキストでの実行では確認できないことが原因です。

修正後は、作業していたシナリオだけでなく、ファイル全体を実行してください。 ある会話に対する修正が、隣接する会話に影響することはよくあります。

繰り返し発生する失敗は、スタックの下位に移してください。 毎回同じように失敗するシナリオは、ターンレベルのバグを示しています。ユニットテストなら、より低コストで再現条件を固定し、より早い段階で検出できます。testing-livekit-agents を参照してください。

関連スキル

• シナリオの作成と整理：writing-livekit-scenarios
• 失敗の対話的なデバッグ：debugging-livekit-agents
• コミットごとのテストを低コストで実施：testing-livekit-agents
• 実行で評価するエージェントのデプロイ：operating-livekit-agents
• フラグ、バージョン、変更履歴：reading-livekit-docs