run-audio-quality-testing

音声品質テストの実行

Coval の音声品質テストをエンドツーエンドで設定し、実行します。音声エージェントを 1 つ、テストセットを 1 つ、音声堅牢性ペルソナパック、共通メトリクスを使用し、Persona でグループ化した複数実行レポートを作成します。公開されているクックブック（https://docs.coval.dev/guides/testing-across-audio-qualities）に沿った内容です。

実行が完了すると、このスキルから analyze-audio-quality-report に引き継ぎ、推奨される修正内容をまとめます。

使用するタイミング

• 「Testing Across Audio Qualities」クックブックに沿って進めたいものの、ペルソナごとに実行を手動で開始したくない場合。
• 音声エージェント（PSTN、SIP、WebSocket、LiveKit、Vapi、OpenAI Realtime、Gemini Realtime など）と、信頼できるテストセットがある場合。
• Persona でグループ化した複数実行レポートの URL を取得し、保存、共有、または分析スキルに渡したい場合。

チャット専用エージェントにはこのスキルを使用しないでください。音声品質テストでは STT、TTS、音声のタイミング、背景ノイズへの対応を検証しますが、チャットエージェントはこれらを実行しません。

前提条件

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 を実行してください。

音声堅牢性ペルソナパック

このクックブックでは、次の 7 つの Coval ペルソナを使用します。各ペルソナは、現実の異なる音声状況を設定します。このスキルでは、ユーザーの組織に次の正確な名前のペルソナがすべて存在することを前提とします。

ペルソナ名	音声の状況
Standard Customer	明瞭な通話での基準となる動作
Impatient Customer	短い回答と低い忍耐力
Confused Customer	明確化への対応
Interruptive Speaker	発話の重なりや割り込みへの対応
Super Fast Speaker	速い話し方
High Background Noise Speaker	背景ノイズへの堅牢性
Low Volume Speaker	音量の小さい話者の音声

ユーザーの組織に不足しているペルソナがある場合は、実行を開始する前に、以下の不足しているペルソナセクションを参照してください。

ワークフロー

ステップ 1：音声エージェントを確認する

$ARGUMENTS にエージェント名または ID が含まれている場合は、それを検索します。含まれていない場合は、音声エージェントを一覧表示し、ユーザーに 1 つ選んでもらいます。

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

必ず 1 つだけ選びます。クックブックでは、すべての実行でエージェントの設定を固定することが明示されています。続行する前にユーザーに確認してください。

エージェントが OpenTelemetry トレースを出力する場合は、ステップ 3 でトレースベースのタイミングメトリクスを含めることを推奨してください。出力しない場合は、トレースの設定（Coval のトレースに関するドキュメントを参照）を推奨するか、トランスクリプトと音声のみのメトリクスで進めることを提案してください。

ステップ 2：テストセットを確認する

coval test-sets list

テストセットを 1 つ選びます。すべてのペルソナで同じテストセットを使用する必要があります。同じサンプルケースを 7 つすべてのペルソナで実行すれば、サブサンプリングも可能です。各実行で固定の --sub-sample-seed（例：42）と同じ --sub-sample-size を使用してください。

ステップ 3：メトリクスを確認する

クックブックでは、タスクの成功と音声経路の挙動を分けることを推奨しています。 ユーザーに、次のグループからそれぞれ少なくとも 1 つのメトリクスを選んでもらいます。エージェントにすでに設定されているメトリクスが適している場合は、それを再利用します。

目標	役立つメトリクス
タスクの結果	複合評価、タスク完了を判定する LLM ジャッジ、またはシナリオ固有の合否メトリクス
応答性	レイテンシー、最初の音声が出るまでの時間、トレース TTFB、プロバイダーの応答時間
音声認識	トレース対象エージェントの STT Word Error Rate、または音声対応の会話の Transcription Error
生成音声の品質	Voice Quality、Speech Artifact Score、およびアーティファクト固有のメトリクス
会話の流れ	割り込み率、無音、感情、ターン単位のタイミング

manager_audio_frequency は含めないでください。これは信号の特性を測定するものであり、知覚される音声品質を測定するものではありません。

この一般的なワークフローでは、STT Word Error Rate (Audio Upload) を推奨しないでください。これは、参照用の書き起こしを含むアップロード音声をテストセットで使用する場合にのみ適用されます。通常の音声シミュレーションの一括実行とは異なる設定です。

coval metrics list

選択したメトリクス ID をカンマ区切りの文字列にまとめ、起動手順で使用します。エージェントのデフォルトのメトリクスを使う場合は、起動コマンドで --metric-ids を省略します。

ステップ 4：ペルソナ ID を解決する

audio-robustness pack 内のすべてのペルソナについて、名前が完全に一致するものを検索し、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

いずれかのペルソナが見つからない場合は、起動前にペルソナが見つからない場合に進みます。

ステップ 5：実行を開始する

ペルソナごとに 1 つ、合計 7 つの実行を開始します。すべての実行で同じエージェント、テストセット、メトリクス、および（サブサンプリングを行う場合は）同じ --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）もサポートされています。1 回の HTTP 呼び出しで済ませたい場合に利用できます。CLI は現在、バッチ起動に対応していません。

ステップ 6：完了を確認する

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

coval runs watch は、実行が最終ステータス（COMPLETED、FAILED、または CANCELLED）に達するまで待機します。7 件すべてを同時に監視する場合は、並列のシェルまたはバックグラウンドジョブで実行します。

いずれかの実行が FAILED で終了し、total_test_cases=0 の場合、実行セットアップワーカーはサブサンプリングの前にクラッシュしています。その実行のみを --sub-sample-size 1 を指定して再起動するか、サブサンプリングを省略してください。また、この失敗を Coval の問題として報告してください。この事象は一部の組織で確認されています。

ステップ 7：複数実行レポートの URL を作成する

7 つの実行 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>

不足しているペルソナ

audio-robustness pack 内のペルソナがユーザーの組織に存在しない場合は、次の2つの方法があります。

1. 推奨 — Coval アプリから作成します。 audio-robustness のペルソナは、Coval のペルソナライブラリにテンプレートとして用意されています。Coval アプリで Personas → New Persona を開き、対応するテンプレートを選択してから、Step 4 を再実行します。テンプレートには、各条件に適した voice_name、background_sound、voice_volume、voice_speed が設定されています。

2. CLI で代替 — 明示的な設定を指定して作成します。 各ペルソナには、発信者の役割を説明する明確な persona_prompt と、1つ以上の音声条件フィールド（background_sound、voice_volume、voice_speed など）が必要です。フィールドの一覧については、ペルソナ作成スキルとCoval のペルソナリファレンスを参照してください。手動で作成したペルソナはテンプレートと動作が完全には一致しない可能性があるため、可能であれば方法1を優先してください。

実行を開始するために、ペルソナ ID を捏造したり、ペルソナを省略したりしないでください。 音声条件が1つでも欠けると、このクックブックのグループ比較が成り立たなくなります。

出力形式

スキルの完了時に、実行可能な短い要約を返します。

## 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.

ガードレール

• 7つすべての実行で、1つのエージェント、1つのテストセット、同じメトリクス、同じサブサンプルシードを使用します。いずれかが異なると、レポートの前提となるグループ比較が成り立たなくなります。
• スイープの途中でエージェントの設定を変更しないでください。変更が必要な場合は、比較条件を同一に保つため、新しいスイープを開始してください。
• チャット専用のエージェントは使用しないでください。このクックブックは明示的に適用対象外です。
• 組織でその条件を「使っていない」という理由で、ペルソナを省略しないでください。比較を解釈可能にするには、パック全体が必要です。
• manager_audio_frequency を、知覚される音質スコアとして提示しないでください。
• ペルソナ、エージェント、テストセット、メトリクスの ID を捏造しないでください。必ずユーザーの組織から特定してください。