run-audio-quality-testing

运行音频质量测试

端到端设置并启动 Coval 音频质量测试：一个语音 Agent、一个测试集、音频稳健性角色包、共享指标，以及按 Persona 分组的多轮运行报告。此流程参考了公开的操作指南： https://docs.coval.dev/guides/testing-across-audio-qualities。

运行完成后，本技能会交由 analyze-audio-quality-report 生成推荐修复方案说明。

适用场景

• 用户想按照“Testing Across Audio Qualities”操作指南执行，但不想手动逐个启动角色测试。
• 用户有一个语音 Agent（PSTN、SIP、WebSocket、LiveKit、Vapi、OpenAI Realtime、Gemini Realtime 等）和一个可信的测试集。
• 用户想要一个按 Persona 分组的多轮运行报告 URL，以便保存、分享或交给分析技能处理。

不要将此技能用于仅支持聊天的 Agent。音频质量测试会测试 STT、TTS、音频时序和背景噪声处理，而聊天 Agent 不会涉及这些内容。

前置条件

coval --version    # CLI must be installed (brew install coval-ai/tap/coval)
coval whoami       # must be authenticated to the right org

如果 coval whoami 失败，请先运行 coval login。

音频稳健性角色包

操作指南使用以下七个 Coval 角色。每个角色都配置了不同的真实音频条件。此技能要求用户的组织中存在名称完全一致的全部七个角色。

角色名称	音频条件
Standard Customer	基准清晰通话行为
Impatient Customer	答复简短、耐心较少
Confused Customer	澄清处理
Interruptive Speaker	重叠说话和打断处理
Super Fast Speaker	语速快
High Background Noise Speaker	背景噪声稳健性
Low Volume Speaker	说话人音量低

如果用户的组织中缺少任何角色，请在启动前参阅下方的缺少的角色部分。

工作流

步骤 1：确认语音 Agent

如果 $ARGUMENTS 中包含 Agent 名称或 ID，请查找该 Agent。否则，列出语音 Agent 并让用户选择一个：

coval agents list --format json | jq '.[] | select(.model_type | test("VOICE|REALTIME|WEBSOCKET")) | {id, display_name, model_type}'

必须且只能选择一个。操作指南明确要求：所有运行中的 Agent 配置保持不变。继续前请与用户确认。

如果 Agent 会生成 OpenTelemetry 跟踪数据，建议在步骤 3 中加入基于跟踪数据的时序指标。如果不会，建议设置跟踪数据（参阅 Coval 跟踪数据文档），或仅使用转录和音频指标继续。

步骤 2：确认测试集

coval test-sets list

选择一个测试集。所有角色测试都必须使用同一个测试集。可以对测试集进行子采样，但七个角色都必须运行相同的采样用例——使用固定的 --sub-sample-seed（例如 42），并在每次运行时设置相同的 --sub-sample-size。

第 3 步：确认指标

该操作指南建议将任务成功情况与音频路径表现分开评估。请帮助 用户从以下各组中至少选择一项指标；如果 Agent 已经附加了合适的指标， 请重复使用。

目标	实用指标
任务结果	综合评估、任务完成情况 LLM 评审，或特定场景的通过/失败指标
响应速度	延迟、首次音频时间、追踪 TTFB、提供商响应时间
语音识别	追踪型 Agent 的 STT Word Error Rate，或音频对话的 Transcription Error
生成语音质量	Voice Quality；Speech Artifact Score 和特定伪音指标
对话流程	打断率、静音、情感、轮次级时序

不要包含 manager_audio_frequency——它衡量的是信号 特征，而非主观感知的音频质量。

对于这一通用 工作流，不要推荐 STT Word Error Rate (Audio Upload)。它仅适用于测试集使用带有参考转录文本的上传音频的情况，与常规语音模拟扫描的设置不同。

coval metrics list

将所选指标 ID 收集为逗号分隔的字符串，以供启动 步骤使用。如果用户希望使用 Agent 的默认指标，则启动调用时完全省略 --metric-ids。

第 4 步：解析 Persona ID

对于音频稳健性套件中的每个 Persona， 通过精确名称匹配解析其 ID：

for name in "Standard Customer" "Impatient Customer" "Confused Customer" \
            "Interruptive Speaker" "Super Fast Speaker" \
            "High Background Noise Speaker" "Low Volume Speaker"; do
  coval personas list --filter "name:\"$name\"" --format json \
    | jq -r --arg n "$name" '.[] | select(.name == $n) | "\(.id)\t\(.name)"'
done

如果有任何 Persona 未返回结果，请在启动前跳转到缺失的 Persona。

第 5 步：启动运行

启动七个运行，每个 Persona 一个；使用相同的 Agent、测试集、指标， 以及（如果进行子采样）相同的 --sub-sample-seed。使用共享标签，方便之后 查找这些运行。

SUB_SAMPLE_SEED=42
SUB_SAMPLE_SIZE=0   # 0 = all cases; set to a positive integer to subsample
CONCURRENCY=5
TAGS="audio-quality-testing,cookbook"
metric_args=()
if [ -n "${METRIC_IDS:-}" ]; then
  metric_args=(--metric-ids "$METRIC_IDS")
fi

for persona_id in "$STANDARD_ID" "$IMPATIENT_ID" "$CONFUSED_ID" \
                  "$INTERRUPTIVE_ID" "$SUPER_FAST_ID" \
                  "$HIGH_NOISE_ID" "$LOW_VOLUME_ID"; do
  coval runs launch \
    --agent-id "$AGENT_ID" \
    --persona-id "$persona_id" \
    --test-set-id "$TEST_SET_ID" \
    "${metric_args[@]}" \
    --concurrency "$CONCURRENCY" \
    --sub-sample-size "$SUB_SAMPLE_SIZE" \
    --sub-sample-seed "$SUB_SAMPLE_SEED" \
    --tags "$TAGS" \
    --name "Audio Quality — $persona_id" \
    --format json
done

记录每次启动响应中的所有 run_id。

**提示：**公共 API 也支持批量启动 （POST /v1/runs/batch），如果你更倾向于只发起一次 HTTP 调用。CLI 目前不提供 批量启动功能。

第 6 步：等待完成

for run_id in "${RUN_IDS[@]}"; do
  coval runs watch "$run_id"
done

coval runs watch 会一直阻塞，直到运行达到终态（COMPLETED、 FAILED 或 CANCELLED）。如果想同时监视全部七个运行，请在并行的 Shell 或后台任务中执行这些命令。

如果任何运行以 FAILED 结束，且 total_test_cases=0，则说明运行设置 工作进程在子采样之前崩溃。使用 --sub-sample-size 1（或省略子采样）重新启动该单个运行，并将故障报告为 Coval 问题——某些组织中出现过这种情况。

第 7 步：构建多运行报告 URL

连接七个运行 ID 并生成报告 URL：

RUN_IDS_CSV=$(IFS=,; echo "${RUN_IDS[*]}")
ORG_SLUG=$(coval whoami --format json | jq -r '.organization.slug')
echo "https://app.coval.dev/${ORG_SLUG}/reports/new?run_ids=${RUN_IDS_CSV}"

告知用户：

1. 打开该 URL。
2. 将 Compare by 设置为 Persona。
3. 使用描述性名称保存报告（这样后续查看者也能保留分组）。
4. 如果希望在无需 Coval 登录的情况下分享，请使用报告的 Share 按钮发布可分享链接。

第 8 步：交接分析

保存报告后，指引用户前往 analyze-audio-quality-report，获取 结构化的下一步修复说明。分析技能会根据分组报告给出有关提示词、工具处理、STT/TTS 或覆盖范围的建议。

建议将已保存的报告 URL 粘贴到：

Use the Coval `analyze-audio-quality-report` skill on this report:
<paste saved report URL>

缺少角色

如果用户组织中不存在音频鲁棒性套件中的任何角色，你有两个选择：

1. 推荐 — 通过 Coval 应用创建。 音频鲁棒性角色作为模板提供于 Coval 角色库中。在 Coval 应用中打开角色 → 新建角色，选择匹配的模板，然后重新运行步骤 4。这些模板包含每种情况对应的正确 voice_name、background_sound、voice_volume 和 voice_speed。

2. CLI 备用方案 — 使用明确配置创建。 每个角色都需要清晰描述来电者角色的 persona_prompt，以及一个或多个音频条件字段（background_sound、voice_volume、voice_speed 等）。完整字段列表请参阅角色创建技能和 Coval 角色参考。手动创建的角色可能无法与模板行为完全一致 — 尽可能优先选择方案 1。

不要编造角色 ID，也不要跳过某个角色来启动运行。 缺少一种音频条件，就会导致本操作手册的分组比较失效。

输出格式

技能完成后，返回简短且可执行的摘要：

## Audio Quality Testing — Launch Summary

**Agent:** <display_name> (<id>)
**Test set:** <display_name> (<id>)
**Subsample:** <sub_sample_size> cases (seed <sub_sample_seed>) — or "full test set"
**Metrics:** <comma-separated metric names>

**Runs:**
| Persona | Run ID | Status | Run link |
|---|---|---|---|
| Standard Customer | … | … | https://app.coval.dev/<org>/runs/<id> |
| Impatient Customer | … | … | … |
| Confused Customer | … | … | … |
| Interruptive Speaker | … | … | … |
| Super Fast Speaker | … | … | … |
| High Background Noise Speaker | … | … | … |
| Low Volume Speaker | … | … | … |

**Multi-run report:**
https://app.coval.dev/<org>/reports/new?run_ids=<csv> — open and set **Compare by → Persona**, then save.

**Next step:** run the `analyze-audio-quality-report` skill on the saved report.

防护措施

• 在全部七次运行中，使用同一个 Agent、同一套测试集、相同指标和相同的子样本种子。任何偏差都会破坏报告所依赖的分组比较。
• 不要在扫描过程中更改 Agent 的配置。如果必须更改，请启动一轮新的扫描，以确保比较公平。
• 不要使用仅支持聊天的 Agent。本操作手册明确不适用。
• 不要因为组织“不会使用”某种条件就跳过对应角色。完整套件才能确保比较结果可解释。
• 不要将 manager_audio_frequency 作为感知音频质量评分。
• 不要编造角色、Agent、测试集或指标 ID — 始终从用户的组织中解析这些 ID。