testing-livekit-agents

LiveKit エージェントのテスト

ターン単位のテストは、エージェントに対する最も低コストで継続的な検証です。ユーザーが既に使っているテストスイートでテキストモードで実行でき、コミットごとに実行しても十分に高速です。フレームワークのヘルパー名やシグネチャは変わるため、記述する前に reading-livekit-docs で調べ、不足している API の詳細はすべてテストのドキュメントページを参照してください。

すべてのテストは同じ形です。テスト対象のエージェントでテストセッションを開始し、ユーザーのターンを 1 回実行して、そのターンで発生したイベントを検証します。

テストで検証する内容

1 回のターンで一連のイベントが発生します。単純なターンは 1 つのメッセージです。より一般的なターンでは、ツールの呼び出し、その出力、必要に応じてハンドオフがあり、最後にメッセージが続きます。テストでは、この一連のイベントを順にたどって各イベントを検証し、最後にターンが終了していることを検証します。

検証には 3 種類あり、このスキルの大半はその使い分けを理解することです。

構造検証では、メッセージのロール、ツールが呼び出されたこと、その引数、返された内容、特定のエージェントへのハンドオフが行われたことを確認します。決定的で、失敗する理由も明確なので、優先して使ってください。

LLM による判定では、LLM 判定ヘルパーを使って、1 つのメッセージと意図の文字列をモデルに渡し、一致しているかどうかを尋ねます。厳密には検証できない返信内容に使います。意図は言い回しではなく、結果（「予約が確定したことと時刻をユーザーに伝える」など）で説明してください。

会話全体の検証では、判定グループヘルパーを使い、複数の組み込み判定器を会話履歴全体に対して並行実行して、判定を集約します。組み込み判定器は、根拠との整合性、関連性、安全性、タスクの完了、ツールの使用といった観点をカバーします。現在の判定器一覧はドキュメントを参照してください。複数のターンにまたがる質問には、これを使ってください。

目安：

• まず構造を検証し、残った部分だけを判定します。 構造検証できる内容を判定で検証すると、遅くなり、失敗しやすくなります。
• ターンを終了させます。 それ以上イベントがないことを検証してください。そうしないと、意図していない動作をエージェントがしていてもテストが成功する可能性があります。
• 1 つのテストにつき 1 つの動作を検証します。 6 つの項目を検証するテストが失敗しても、ほとんど何も分かりません。

ツールのモック

テストで実際のバックエンドにアクセスすると、テストスイートが遅くなり、非決定的になるため、アクセスしないでください。テスト対象のエージェントのツールをオーバーライドし、固定値を返します。

API のほかに、次の 2 点に注意してください。

• 成功だけでなく失敗もモックします。 モックからエラーを返すとツールが例外を発生させるため、バックエンドが停止したときにエージェントが何を言うかをテストできます。ほとんどのエージェントにはこのテストがなく、ユーザーが最も気づきやすい動作です。
• 適用範囲が重要です。 デフォルトでは、モックは独自の run() 呼び出しを囲むブロック内で適用されます。これはテストに必要な動作です。独立して実行され、ライフサイクル全体でモックを有効にする必要があるセッション向けに、セッションスコープの形式もあります。シミュレーションのエントリーポイントではこの形式を使いますが、テストでは使いません。writing-livekit-scenarios を参照してください。

モックで変わるのは実行だけです。モデルには実際のツールスキーマが引き続き渡されるため、ツールの選択もテスト対象です。

複数ターンと履歴のシード

以前のターンに依存する動作をテストする方法は 2 つあります。

• ターンを実行します。 ターンごとに会話履歴に追加されるため、2 回目のターンでは 1 回目の内容が参照されます。詳細を複数ターンにわたって集める場合、フローの途中でユーザーが考えを変える場合、ハンドオフでコンテキストを引き継ぐ場合など、経路が重要なときに使います。
• 履歴をシードします。 チャット履歴を作成してエージェントに渡し、確認したい状態から開始します。テスト対象ではない準備用のターンを省きたいときに使います。6 回目のターンにたどり着くために 5 回分のターンを再生するより速く、壊れにくい方法です。

テスト対象

重要度のおおよその順です。

1. ユーザーが求めた動作。 どのエージェントにも最低限これが必要です。
2. ツールの呼び出し：代表的なリクエストに対して、適切なツールに適切な引数を渡すこと。
3. ツールの失敗：ツールがエラーを返したり、何も返さなかったりしたときに、エージェントが何を言うか。
4. 拒否と制限：エージェントが拒否すべき要求を拒否し、持ち得ないデータをでっち上げないこと。拒否できることが合格条件です。
5. 引き継ぎ：適切なタイミングで移行が行われ、次のエージェントに必要な情報が渡されること。
6. 修正したバグすべて。 テストがなければ、修正済みのバグが気付かれないまま再発する可能性があります。

区別しておくべき3種類のエビデンス

予約、編集、確認などを行うエージェントのテストスイートには、3種類のテストが必要です。これらを混同すると、テストがすべて合格していても、壊れたエージェントをリリースすることになります。

• 決定論的なアプリケーションテストでは、アプリケーションのコアを直接対象に、ガード、何もしない動作、空の値と不明な値の違い、訂正、ストレージの失敗、再試行を検証します。高速かつ正確で、モデルは不要です。
• スクリプト化されたプロバイダーを使う実際のSDKテストでは、イベントの配線とツールの連携を検証します。リスナーが実行されること、ツールがセッションから送信された内容を受け取ることを確認します。スクリプト化されたプロバイダーで証明できるのは仕組みであり、言語理解ではありません。指定した文は要件ではなく、テスト用の固定データです。
• 実際のモデルを使う自然な言葉でのテストでは、呼び出し側が普段使う話し方から、モデルがタスクを完了できることを検証します。プロンプトにない言い換え、同意に混じる訂正、異なる質問への答えとなる同じ短い返答などが対象です。

テストに見えても実際はそうではない近道として、インタラクションを通さずヘルパーを呼び出したりプライベートな状態を埋めたりすること、どのツールを指定するかをテストの呼び出し側に教えること、正しさを検証する対象の変更処理そのものをモックすること、出力をアプリケーション独自のエクスポーターとだけ比較すること、失敗したターンが通るまで再試行すること、失敗したアサーションを削除することがあります。

正しい動作を罰するテストを書かない

最もよくある不適切なエージェントテストは、エージェントがすべきでないことを実行するよう要求するものです。知り得ないデータを述べる、具体的な医療・法律・金融上の推奨を行う、阻止すべきフローを完了するといったケースです。誤った動作をしなければ合格できないなら、テストを修正してください。

ガードレールの合格条件は、エージェントが拒否する、エスカレーションする、または情報をでっち上げないことです。そのようにアサーションを記述してください。

位置づけ

• 構築中のインタラクティブな操作確認 → debugging-livekit-agents。反復が速く、アサーションは保持しません。
• ターン単位の決定論的なテストを、すべてのコミットで実行 → ここです。最も低コストで、長く役立つチェックです。
• リリース前に、シミュレーションされたユーザーが会話全体を評価 → running-livekit-simulations。よりコストがかかりますが、ターン単位のテストでは見つからない創発的な動作を検出できます。

シミュレーションで同じ失敗が繰り返される場合、原因はたいていターン単位にあります。原因をより正確に特定し、より早く検出できるよう、ここでテストを書いてください。

関連スキル

• 現在のAPIサーフェス：reading-livekit-docs
• 最初にバグを見つける：debugging-livekit-agents
• シード状態やセッションスコープのモックを含むシミュレーション：writing-livekit-scenarios、running-livekit-simulations