writing-livekit-scenarios

シミュレーションシナリオの作成

シナリオは、シミュレートするユーザーの**instructions（ユーザーがどのような人物で、何を求めているか）と、成功とみなされる条件を示すagent_expectations**で構成されます。シミュレーションでは、実際のエージェントに対してシナリオを実行し、LLM の判定者が会話記録を評価します。

実行は使い捨てです。残るのはシナリオファイルです。差分でレビューされ、何年にもわたって再実行され、誰にも気づかれずに何かを壊してしまうプロンプトの編集を検出します。

ファイルを作成する前に、reading-livekit-docs で正確なスキーマと CLI フラグを確認してください。フィールド名やコマンドは変更されるため、このスキルではそれらを再掲しません。概念としては、ファイルには名前付きのシナリオグループが含まれます。各シナリオには、シミュレートするユーザーの指示、合格基準、さらに任意でグループ化用のタグや、エージェントが実行時に参照できるシナリオごとのデータが含まれます。CLI がファイルへのシナリオごとの安定した ID の追加を提案した場合は、承諾してコミットしてください。

生成されたベースラインから始める

空のファイルから始めないでください。LiveKit のジェネレーターはエージェントのソースを読み取り、シナリオを手作業で 10 件作成するよりもずっと速く、十分な初稿を生成します。

lk agent simulate text -n 10    # confirm the exact flags with --help

**ソースからの生成ではコードが LiveKit Cloud にアップロードされます。**ジェネレーターがコードを読み取るためです。そのため、CLI は事前に確認を求めます。実行前にユーザーへ説明し、拒否できるようにしてください。マシンの外に出せないコードもあり、その場合はシナリオを手作業で作成します。対話なしで実行する場合は、フラグで確認プロンプトをスキップできます。

実行が完了すると、CLI は生成されたシナリオの保存先を通知するか、プロジェクトへの保存を提案します。どちらの場合も、そのファイルをリポジトリに追加し、出発点にしてください。

ジェネレーターの出力は調整できません。コードから意図を推測するため、このエージェントのユーザーが実際に行う会話ではなく、もっともらしい会話を作成します。また、ユーザーが何を心配しているかも把握していません。出力はあくまで草案として扱ってください。

1. すべてのシナリオを読み、重要でないものは削除してください。読んでいないファイルはテストスイートではありません。
2. **曖昧な期待を明確にします。**判定者がagent_expectationsを判断できない場合、判定結果は実行のたびに変わります。シナリオが不安定になる最大の原因です。
3. **生成で見落とされた内容を追加します。**生成結果はハッピーパスに偏りがちです。references/risk-coverage.mdでは、エージェントの制約をチェックリストにまとめ、各項目にシナリオを割り当てる方法を説明しています。
4. **ユーザーが心配している内容を追加します。**ユーザーから話がなければ、何を重点的にストレステストしたいか尋ねてください。人が調整するスイートが生成されたものより優れているのは、その入力があるためです。

何を検証するか尋ねる

どのフローが繰り返し壊れるのか、どの顧客から苦情があったのか、どの変更を不安に思っているのかは、ユーザーが知っています。尋ねたうえで、その領域にシナリオを多く、より深く割り当ててください。

重点化によってカバレッジを増やしますが、エージェントの厳格な制限に対するカバレッジを減らしてはいけません。ユーザーに希望がない場合は、幅広く生成し、その旨を伝えてください。

エージェントにできることに基づいてシナリオを作成する

何かを書く前に、通常のツールを使ってエージェントのコードをローカルで読んでください。ユーザーが依頼できること（機能）、依頼がブロックされる条件（制約：必須手順、名前で指定された利用不可項目、上限、利用資格）、そしてエージェントが拒否しなければならないことを確認します。

特に重要なのは制約です。エージェントにできないことを依頼するシナリオが有効なのは、エージェントがその旨を伝えることが期待されている場合に限られます。逆の書き方をすると、エージェントが正しく振る舞ったときにテストが失敗します。

対象範囲は、セッションのエントリーポイントから到達可能なエージェントに加えて、そこから引き継がれるエージェントと、完了を待つタスクです。ディレクトリ内のその他のクラス、未使用のインポート、サンプルファイルは無視してください。

模レートされたユーザーが従える指示を書く

使用する形式は2種類あり、シナリオの目的に応じて使い分けます。詳細と例については、references/scenario-craft.md を参照してください。

• 箇条書き形式の指示は、最終状態で評価する決定論的なフローに使います。構造化されたテンプレート（ペルソナ、最初の発言、尋ねられた場合のみ明かす事実、順序どおりの手順、条件付きの応答）を使うと、ペルソナモデルを適切な状態に保ち、実行を再現可能にできます。
• ペルソナの段落と目標は、会話のみで評価する自由度の高いシナリオや敵対的なシナリオに使います。模擬ユーザーに即興で対応させたい場合に適しています。

どちらの形式でも、目標はエージェントに対する依頼であり、エージェント自身が行う行動ではありません。エージェントのドメインにおける実際の値を使い、事前状態がないことを前提とします。ペルソナ、気分、難易度に変化をつけ、協力的なユーザーばかりのシナリオを並べないようにします。

シナリオをセットに分け、セットごとに1つのファイルを使う

実行コマンドが受け取るシナリオファイルは1つなので、1ファイルが1回の実行単位です。通常はトピックではなく、個別に実行したい基準に沿って分けます。

最も重要な基準は、セットの評価方法です。

• 具体的なツールフローを実行して決定論的な最終状態に到達させ、最終状態と会話の両方で評価するシナリオ（下記の「エージェントにシナリオを利用させる」を参照）。
• agent_expectations のみで評価する、自由度の高いシナリオや敵対的なシナリオ。

これらには異なる形式の指示、異なるエージェントの接続方法が必要で、実行頻度も異なることがよくあるため、別々のファイルに入れます。2つ目の基準は実行頻度です。マージ前に実行する小規模なセットと、リリース前に実行する全シナリオを用意します。

各ファイルには、セットの内容を表す name を付けます。実行時のラベルとして使われるためです。ファイル内では tags を使って絞り込みます。失敗したときにエージェントのどの部分に原因があるか分かるよう feature をタグ付けし、さらにフィルタリングに使う項目（チャネル、難易度など）を追加します。ファイルには、そのセットの前提条件を記したヘッダーコメントを付けます。固定された日付、必要な環境変数、期待値が依存する条件を記録してください。

シナリオを再現可能に保つ

シナリオは、今日と同じ結果を数か月後にも返す必要があります。

• 絶対日付を記述し、エージェントの時計を固定します（通常は環境変数を使います）。そうすれば、利用可能性と期待値が常に一致します。相対日付は時間とともにずれていきます。
• **シナリオから実際のバックエンドにアクセスさせないでください。**代わりに、シナリオから決定論的な状態をシードします（下記の「エージェントにシナリオを利用させる」を参照）。
• CLI が対応している場合は、IDを安定させます。ラベルや指示は変わることがありますが、IDによってシナリオの実行履歴を長期にわたって紐付けます。シナリオを一から書き直した場合は新しいシナリオとし、新しいIDを割り当てます。

エージェントにシナリオを利用させる

シナリオファイルだけでは、2つの問題を解決できません。実際のバックエンドにアクセスするシナリオは実行ごとに異なる評価結果となり、トランスクリプトだけを読む評価器では、誤った部屋を予約した実行でも合格してしまいます。どちらもエージェントのコードの、エントリーポイント上部にある1つの分岐で解決します。

1. ジョブコンテキストからシミュレーションを検出します。本番環境ではチェック結果が空になり、それ以外は何も変わりません。
2. シナリオごとのデータ（偽のカレンダー、インメモリデータベース）を使って状態をシードします。エージェントの実際のツールは、変更されることなくその状態を読み取ります。
3. セッションの間、ツールをモックします。これにより、ツール選択は引き続きテスト対象となり、実行は決定論的になります。
4. シミュレーション終了時のコールバックで最終状態を評価します。エージェントの最終状態をシナリオの期待値と比較し、一致しない場合は実行を失敗にします。このチェックにより、評価器が合格とした実行を失敗にできますが、評価器が失敗とした実行を合格にすることはできません。

これはツールフローのシナリオにのみ必要です。自由度の高いシナリオや敵対的なシナリオは、会話のみで評価します。references/connecting-the-agent.md で、配線が反映されたことの確認方法も含め、詳細を説明しています。最新の API 名は reading-livekit-docs で確認してください。

実際の問題からスイートを拡充する

最も価値のあるシナリオは、何かがうまくいかなかった状況を記述したものです。エージェントの稼働開始後は、新しいシナリオを考案するのではなく、記録されたセッションから導き出してください。CLI が対応している場合、サブコマンドを使って記録されたセッションからシナリオを導き出せます（lk agent simulate --help を確認してください）。導き出されたシナリオは1回の呼び出しを記述するため、それが表す呼び出しのクラスに範囲を広げ、期待値を強化して、適用したいルールにしてください。

修正した本番環境のバグはすべて、ファイルに恒久的なシナリオとして追加してください。

悪いテストを書かない

判定では agent_expectations に照らしてエージェントを評価するため、期待値を不注意に設定すると、正しい動作が不当に低く評価されます。

• ガードレールや否定的なケースでは、エージェントが拒否する、エスカレーションする、またはデータを捏造しないことが合格となります。そのように期待値を記述してください。
• 知り得ないデータの提示や、具体的な医療・法律・金融上の指示など、不適切な振る舞いをしなければ満たせない期待値は、決して書かないでください。合格に不適切な振る舞いが必要なら、そのシナリオは誤りです。
• ユーザーの視点から、結果で評価してください。言い回しを指定しないでください。

参考資料

• references/risk-coverage.md — 制約をチェックリストに変換し、網羅性を保証する方法
• references/scenario-craft.md — 指示の形式、ペルソナの多様性、音声に特化したシナリオ
• references/connecting-the-agent.md — エージェント側のコード：検出、シード、モック、最終状態の評価

関連スキル

• 実行方法：running-livekit-simulations
• スキーマと CLI の情報：reading-livekit-docs