simulations

Vapi Simulations

5つのレイヤーで現実的な会話テストを作成します。パーソナリティがAIテスターを制御し、シナリオがその意図と測定可能な成果を定義し、シミュレーションが両者を組み合わせ、スイートがシミュレーションをまとめ、実行がアシスタントまたはスクワッドに対してテストを実行します。

ソースと安全性のルール

• ペイロードを送信する前に、現在のVapiドキュメントMCP、APIリファレンス、または公開OpenAPI仕様と照合して、実際のペイロードを検証してください。シミュレーションでは、/eval/simulation APIファミリーを使用します。
• APIキー、プロバイダーのシークレット、認証情報の値、非公開のWebhook URL、実際の顧客データを表示したり、チャットで要求したり、埋め込んだりしないでください。
• シミュレーションの実行は外部アクションとして扱ってください。クレジットを消費したり、同時実行枠を使用したり、Webhookを送信したり、モックされていない限り対象の実際のツールを呼び出したりする可能性があります。
• ユーザーから明確に要求されていない限り、リソースの実行、キャンセル、更新、削除は行わないでください。変更が要求されていない場合は、設定案を作成してください。
• すべてのアシスタント、スクワッド、パーソナリティ、シナリオ、シミュレーション、スイート、ツール、構造化出力、認証情報のIDは、ユーザーの入力またはAPIから取得してください。IDを捏造しないでください。
• レガシーのTest Suitesは作成しないでください。決定論的なターンごとのチェックにはEvalsを、チャットや音声での動的な会話にはSimulationsを使用してください。

手順

1. テストの種類と実行モードを選択します。

   • 複数ターンの動作、パーソナリティのバリエーション、スクワッドへの引き継ぎ、現実的なツールの呼び出し経路、または音声の動作には、Simulationsを使用します。
   • 正確な応答、正規表現、固定のモック会話、またはツール呼び出し引数の厳密なチェックが要件の場合は、代わりにEvalsを使用します。
   • ユーザーが設計、草案作成、レビュー、説明を求めている場合は、テスト計画またはペイロードを返します。明示的に要求され、VAPI_API_KEYが利用可能な場合にのみ、実際の変更を行います。

2. 対象と既存のテストリソースを確認します。

   • アシスタントまたはスクワッドを取得し、主要な経路、ガードレール、ツール、変数、言語、障害時の動作を特定します。
   • 重複を作成する前に、既存のパーソナリティ、シナリオ、シミュレーション、スイート、再利用可能な構造化出力を一覧表示します。
   • 意図と設定が明確に一致する場合にのみ、既存のリソースを再利用します。それ以外の場合は、目的が明確に分かる名前の新しいリソースを作成するか、候補から選ぶようユーザーに尋ねます。

3. 要件をテスト可能な記述に変換します。

   • ユーザー、ドキュメント、トランスクリプト、または対象のプロンプトやツールから要件を収集します。2人のレビュー担当者が同じ合否判定に至るまで各要件を書き直します。「エージェントがエラーに適切に対処する」を、「スケジューリングツールが失敗した場合、エージェントは変更が確定していないと伝え、安全な次の手順を提示する」のように具体化します。
   • 各要件の出典を記録します。曖昧な要件や出典のない要件は推測せず、未解決の質問として返します。
   • 各要件に、高影響（データ、金銭、許可されていない変更、エスカレーションの見落とし、法的リスク）、高頻度（エージェントの主な業務）、または高不確実性（新規、最近変更された、一貫性がない、ツールに依存する）のタグを付け、それらを最優先で網羅します。
   • 受付テーブル、目標ごとのチェックリスト、記述ルール、リリース準備リストについては、Coverage planningを参照してください。これらは「Public Sources」にリンクされているVapiのテストガイダンスを要約したものです。

4. ペイロードを作成する前に、テスト範囲を設計します。

   • コアパスのスモークシミュレーション、必須の真偽値の結果を1～2件、チャットのトランスポート、1回の反復から始めます。
   • 主な目標ごとに、次の順序でカバーします。コアとなる結果、呼び出し側のバリエーション、情報の不足または不明確さ、ツールやサービスの障害からの復旧、ガードレール、リクエストに応えられない場合の安全な代替策、スクワッドに照らした引き継ぎの品質、音声の確認、既知の本番障害の回帰テスト。
   • 影響の大きいルールはすべて、両方向でテストします。エージェントが動作するケースと、拒否または保留すべきケースです。成功後に詳細を共有することを検証する場合は、失敗後に詳細を共有しないパートナーシナリオも用意します。
   • 修正した不具合の回帰シミュレーションを追加します。曖昧さ、中断、拒否、依存関係の利用不可、ツールの失敗、エスカレーション、引き継ぎについては、それぞれ個別のエッジケースを追加します。
   • シナリオの意図、パーソナリティの動作、評価基準は独立させ、それぞれ再利用できるようにします。
   • リソース名には実装の詳細ではなく、動作と期待される結果を使用します。シナリオとパーソナリティの組み合わせごとに、固有のシナリオ名を付けます。実行ビューではシナリオ名ごとに結果が表示されるため、複数のパーソナリティで1つのシナリオを共有すると、同一の行として表示されます。
   • ペイロードを作成する前に、要件ごとに1行を割り当て、対応するシナリオ、方向、トランスポートを示したカバレッジマトリックスとして計画を報告します。

5. パーソナリティを定義します。

   • 適切な既存のパーソナリティがある場合は、それを優先します。
   • 新しく作成する場合は、AI テスター用の完全で有効なアシスタント設定を指定します。安定した気質、話し方、呼び出し側の振る舞いはシステムプロンプトに記述し、状況固有の目標はシナリオに記述します。
   • 利用可能な場合は、create-assistant スキルを使用して、パーソナリティのアシスタント設定を組み立てるか、検証します。
   • 音声の実行で必要な場合に限り、音声と文字起こしを設定します。チャットの実行ではパーソナリティのモデルを使用しますが、音声経路はスキップします。

6. シナリオと評価を定義します。

   • instructions には、AI テスターの意図と事実を記述します。対象のアシスタントの回答を台本のように指定せず、目標と制約を説明し、呼び出し側がいつ会話を終了すべきかも記載します。
   • 各評価では、観測可能な結果を1つだけ測定します。合否の事実には説明的な真偽値の出力を、しきい値には数値の出力を優先します。「時間を確認し、代替案を提示した」は2つの評価に分け、失敗した場合に何ができなかったのかが1つだけ分かるようにします。
   • 対象のアシスタントの主張ではなく、記録された事実を判定します。予約が成功と見なされるのは、アシスタントが呼び出し側に問題ないと伝えたときではなく、ツールの結果が成功を報告したときです。各説明では、成功と見なす条件を正確に明記し、異なる言い回しや手順も許容します。
   • チャットモードで実行するすべてのシナリオに、テキストベースの必須評価を少なくとも1つ含めます。音声のみの評価はチャットの実行ではスキップされ、必須評価がすべてスキップされるシナリオは、何も検証せずに合格します。
   • structuredOutputId またはインラインの structuredOutput のどちらか一方を指定し、両方は指定しません。インライン出力には name と JSON の schema が必要です。
   • 期待される value の型を、評価対象のプリミティブ型に合わせます。真偽値と文字列では = または != を使用します。数値型では >、<、>=、<= も使用できます。
   • 重要な基準には required: true を設定します。必須ではない基準は、シミュレーションの失敗につながってはならない診断目的にのみ使用します。
   • オブジェクトの構造化出力は、path を使ってプリミティブなリーフを評価できます。オブジェクトや配列を直接比較しないでください。

7. 副作用と実行時コンテキストを分離します。

   • 実行するたびに、対象に設定されているツールを確認します。実際に実行するとデータを書き込む、人に連絡する、費用が発生する、またはテストの非決定性につながる可能性があるツールはモックします。
   • 各 toolMocks[].toolName は完全一致させます。モックの result は常に文字列です。対象が JSON 形式の出力を想定している場合は、JSON を文字列としてエンコードします。
   • モックしていないツールはすべて、チャットと音声のシミュレーションの両方で実際に動作すると想定します。
   • {{variables}} のテスト値は targetOverrides.variableValues に設定します。合成データを使用し、シークレットは Vapi の認証情報に保存します。
   • simulation.run.started または simulation.run.ended フックは、要求された場合にのみ設定します。インラインの認証ヘッダーより server.credentialId を優先します。

8. 再利用可能なリソースを作成し、検証します。

   • 依存関係の順序に従って作成します。人格とシナリオ、次にシミュレーション、その後に必要であればスイートを作成します。
   • 作成操作では 201 を必須とします。返された ID と、テストを定義するフィールドを確認します。
   • 更新する場合は、まず現在のリソースを取得します。無関係なスカラー値フィールドは省略し、変更する配列には意図した値全体を送信します。スイートの simulationIds と targetAssignments は、既存の配列を置き換えます。
   • 既存のスイートを拡張する場合は、スイートとそのシナリオおよびシミュレーションを取得し、名前で差分を比較します。指示と評価がすでに一致するシナリオは維持し、ユーザーが変更したものだけを更新し、残りを作成します。スイートの simulationIds 全体を、維持する ID の後に新しい ID を並べて送信します。ユーザーがそのシミュレーションを指定した場合にのみ ID を削除します。
   • 予定している更新はすべて、送信前にユーザーに読み上げて確認します。既存のシナリオの評価を変更すると、本番環境での評価基準が変わります。本番環境が依存しているバージョンが既存のものである場合は、新しいシナリオ名で新しい期待値を追加します。
   • 更新後に再取得します。スイートやその他のシミュレーションリソースの削除は取り消せません。先に正確な ID と依存関係への影響を確認します。

9. 慎重に実行します。

   • プロンプト、ツール、会話ロジックをすばやく反復するには、vapi.webchat を優先します。
   • 音声認識、音声出力、割り込み、録音、または最終的なエンドツーエンド検証には、vapi.websocket を使用します。リリースを表明する前に、主要な会話を音声モードで実行します。また、日付、電話番号、コードの数字の正確さを証明するために、音声実行だけに頼らないでください。
   • まず 1 回の反復から始めます。1 回の実行で有効性が確認できた後、動作の一貫性を測定する場合にのみ反復回数を増やします。リリース前には、重要なシナリオを繰り返し実行して反復結果を比較し、平均値は使いません。重要な要件への違反が 1 回でもあれば、原因が説明されるまで動作は不安定と見なします。
   • 実行を送信する前に、対象、シミュレーションまたはスイート、トランスポート、反復回数、ツールのモック、残っている実際の副作用をまとめて確認します。
   • POST /eval/simulation/run で実行を作成し、201 を必須とします。実行 ID と、存在する場合はダッシュボードの url を返します。

10. 結果を監視し、診断します。

• GET /eval/simulation/run/{id} を status が ended になるまでポーリングします。queued または running を成功として扱わないでください。
• GET /eval/simulation/run/{id}/item を取得し、すべてのアイテムを確認します。合格グループには評価対象のアイテムがあり、失敗またはキャンセルされたアイテムがゼロで、必須の評価がすべて合格している必要があります。
• 実際の値と期待値、抽出エラー、スキップされた評価、失敗理由、トランスクリプトの証拠、トランスポート、反復回数を報告します。
• アシスタントを変更する前に、失敗したレイヤーを診断します。対象ランタイムの失敗、シナリオの曖昧さ、パーソナリティの振る舞い、ツールモックの不一致、構造化出力の抽出、またはアシスタントの実際の振る舞いを確認します。
• アシスタントを修正する際も、評価の安定性を保ちます。期待される基準を変更するのは、ビジネス要件が変わった場合に限ります。失敗の説明なしに、基準を緩めたり、合格するまで再実行したりしないでください。
• スイートをリリース可能と判断する前に、カバレッジ計画のリリース準備リストを確認します。主要な目標がすべてエンドツーエンドでカバーされていること、影響の大きいルールが両方向でカバーされていること、各目標に失敗パスがあること、重要なシナリオで繰り返し合格していること、主要な会話を音声で実行していること、そしてトランスクリプトを読み録音を聞いた人がいることを確認します。

11. 失敗を正直に扱います。

• 400 の場合は、リクエストを現在のスキーマと比較し、明確な検証エラーを1つ修正してから、最大1回だけ再試行します。
• 401 または 403 の場合は、認証または権限の問題として処理を停止します。404 の場合は、不足している依存関係を報告します。409 または同時実行エラーの場合は、GET /eval/simulation/concurrency と実行中のランを確認します。5xx の場合は、サービス障害を報告します。
• キュー待ちまたは実行中のグループやアイテムのみをキャンセルします。対応する API レスポンスを確認するまでは、ラン、キャンセル、変更、合格が成功したと主張しないでください。

API の実装

REST コードを作成する場合、ライブリクエストを実行する場合、フックまたはモックを設定する場合、あるいはランの結果を解釈する場合は、事前にシミュレーション API リファレンスを読んでください。現在の公式 Vapi SDK ドキュメントで必要なシミュレーションリソースとメソッドが明示的に公開されている場合を除き、直接 REST を使用してください。SDK メソッド名を決して捏造しないでください。

出力の要件

リクエストに関連するセクションのみを返してください。

• テスト戦略：対象の振る舞い、カバレッジ、Eval ではなく Simulation を選ぶ理由
• カバレッジマトリクス：要件ごとに1行を設け、情報源、優先度、それをカバーするシナリオ、方向、トランスポートを記載
• リソース計画：パーソナリティ、シナリオ、評価、シミュレーション、スイート
• 既存のスイートを拡張する場合のスイート差分：維持、更新、新規作成するシナリオとシミュレーション、維持、追加、削除するスイート ID
• 副作用のレビュー：モックツール、ライブツール、フック、変数、トランスポート、反復回数、予想されるコストと同時実行への影響
• 保存可能な JSON または実装コード
• 変更が成功した場合は、作成されたリソース ID と確認済みのフィールド
• ランがリクエストされた場合は、ラン ID、ダッシュボード URL、ステータス、アイテム数、評価ごとの証拠
• 失敗の診断と、次に推奨する最小限の変更

公開情報源

• 音声エージェントのテスト
• テストカバレッジの計画
• シミュレーションによるテスト結果の評価
• Eval による判断のテスト
• テストの実行と保守
• シミュレーションの概要
• シミュレーションのクイックスタート
• シミュレーションの応用
• シミュレーションの管理
• Vapi API リファレンスの索引と OpenAPI