simulations

Vapi 模拟

通过五个层次构建逼真的对话测试：人格用于控制 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. 将需求转化为可测试的陈述。

   • 从用户、文档、对话记录或目标的提示词和工具中收集需求。逐一改写每项需求，直到两位审查者能得出相同的通过或失败判断：“Agent 能妥善处理错误”应改为“如果日程安排工具失败，Agent 会说明变更尚未确认，并提供安全的后续步骤”。
   • 记录每项需求的来源。对于模糊或没有来源的需求，应将其列为待确认问题，而不是自行猜测。
   • 将每项需求标记为高影响（数据、资金、未经授权的变更、未能升级处理、法律风险）、高频率（Agent 的主要工作）或高不确定性（新推出、近期变更、不一致、依赖工具），并优先覆盖这些需求。
   • 阅读 覆盖规划，查看需求收集表、每个目标的检查清单、撰写规则和启动准备清单。这些内容提炼自“公共来源”下链接的 Vapi 测试指南。

4. 先设计覆盖范围，再编写载荷。

   • 从一次核心路径冒烟模拟开始，涵盖一两个必需的布尔结果、聊天传输方式和一次迭代。
   • 对每个主要目标，按以下顺序覆盖：核心结果、调用方差异、信息缺失或不明确、工具或服务故障恢复、护栏、无法满足请求时的安全替代方案、与团队的交接质量、语音检查，以及已知的生产故障回归测试。
   • 对每条高影响规则，都要测试两个方向：Agent 采取行动的情况，以及必须拒绝或暂缓行动的情况。成功后分享详细信息的验证场景，需要搭配一个失败后不分享这些信息的场景。
   • 为已修复的缺陷添加回归模拟。另为歧义、中断、拒绝、依赖项不可用、工具失败、升级处理和交接设置独立的边缘案例。
   • 将场景意图、个性行为和评估标准彼此独立，以便重复使用。
   • 按行为和预期结果命名资源，而非按实现细节命名。每个场景和个性组合都要使用独立的场景名称；运行视图按场景名称列出结果，因此多个个性共用一个场景时，结果会显示为相同的行。
   • 编写载荷前，先以覆盖矩阵报告计划，每项要求占一行，并列出覆盖它的场景、方向和传输方式。

5. 定义个性。

   • 有合适的现有个性时，优先使用。
   • 创建个性时，为 AI 测试员提供完整且有效的助手配置。将稳定的性情、说话风格和调用方行为放入系统提示词；将具体情境下的目标放入场景。
   • 有 create-assistant 技能时，使用它来组装或验证个性的助手配置。
   • 仅在语音运行需要时配置语音和转录器。聊天运行使用该个性的模型，但会跳过其音频路径。

6. 定义场景和评估。

   • 将 instructions 写成 AI 测试员的意图和事实。描述目标和约束，但不要替目标助手编写回答脚本；同时说明调用方何时应结束对话。
   • 每项评估只衡量一个可观察的结果。通过/失败事实优先使用描述性的布尔输出，阈值优先使用数值输出。将“确认了时间并提供了替代方案”拆分为两项评估，这样失败时就能明确指出具体问题。
   • 判断记录到的事实，而非目标助手的说法：只有工具结果报告成功，预订才算通过，而不是助手说调用方已安排妥当。每项描述都要明确说明成功的判定标准，并允许使用不同措辞和路径。
   • 每个将在聊天模式下运行的场景，至少要包含一项基于文本的必需评估。纯音频评估会在聊天运行中跳过；如果某场景的所有必需评估都被跳过，该场景就会在未验证任何内容的情况下通过。
   • 使用 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。在声称已准备发布前，先以语音模式运行主要对话；不要依靠语音运行来证明日期、电话号码或代码的数字准确性。
   • 从一次迭代开始。只有在单次运行有效后，才增加迭代次数以衡量行为一致性。发布前，重复运行关键场景并比较各次迭代，而非取平均值；只要关键要求有一次未满足，在查明原因前就应视为行为不稳定。
   • 发送运行前，概述目标、模拟或套件、传输方式、迭代次数、工具模拟以及任何仍会实际产生的副作用。
   • 使用 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 时，将请求与当前架构进行比较，修正一个明确的验证问题后，最多重试一次。
• 遇到 401 或 403 时，因身份验证或权限问题而停止。遇到 404 时，报告缺失的依赖项。遇到 409 或并发错误时，检查 GET /eval/simulation/concurrency 和正在运行的任务。遇到 5xx 时，报告服务故障。
• 仅取消排队中或正在运行的组或项目。除非相应的 API 响应已确认，否则绝不要声称运行、取消、变更或通过已成功。

API 实现

在编写 REST 代码、发起实时请求、配置钩子或模拟项，或解读运行结果之前，请阅读Simulation API 参考。除非当前 Vapi SDK 官方文档明确提供所需的 simulation 资源和方法，否则请使用直接 REST；绝不要臆造 SDK 方法名称。

输出约定

仅返回与请求相关的部分：

• 测试策略：目标行为、覆盖范围，以及为何使用 Simulation 而非 Eval
• 覆盖率矩阵：每项要求一行，列出其来源、优先级，以及覆盖该要求的场景、方向和传输方式
• 资源规划：个性、场景、评估、simulation 和测试套件
• 测试套件差异（扩展现有测试套件时）：保留、更新和新建的场景与 simulation；保留、新增和移除的测试套件 ID
• 副作用审查：模拟工具、实时工具、钩子、变量、传输方式、迭代次数，以及预期成本和并发影响
• 可直接保存的 JSON 或实现代码
• 变更成功时创建的资源 ID 和已验证字段
• 请求运行时提供运行 ID、仪表板 URL、状态、项目数量和各项评估的证据
• 失败诊断和建议采取的最小后续变更

公开资料

• 测试语音 Agent
• 规划测试覆盖率
• 使用 Simulations 测试结果
• 使用 Evals 测试决策
• 运行和维护测试
• Simulations 概览
• Simulations 快速入门
• Simulations 高级指南
• 管理 simulations
• Vapi API 参考索引和 OpenAPI