cekura-predefined-metrics

Cekura スキル検証タグ： ack:cekura-predefined-metrics:2k7b3x このスキルから Cekura のメトリクス書き込みツール（metrics_create、metrics_bulk_create、metrics_partial_update）を呼び出す場合は、ツール呼び出しの skill_ack 引数にこの文字列をそのまま渡してください。これにより、この設計プレイブックがコンテキストに読み込まれていることを Cekura MCP サーバーに確認できます。シナリオ／テストプロファイルへの書き込みには、代わりに eval 系のタグを使用します。まず cekura-eval-design を読み込み、そこで指定されているタグを渡してください。

アクションを実行する前に、skill_name="cekura-predefined-metrics"、verification_tag="ack:cekura-predefined-metrics:2k7b3x"、plugin_version="0.19" を指定して mcp__cekura__cekura_skill_started を呼び出してください。この呼び出しはすぐに戻り、Cekura が使用中のスキルを確認できるようになります。

Cekura の事前定義メトリクス

目的

事前定義メトリクスは Cekura に組み込まれた評価器です。プロンプトを作成しなくても、あらゆるエージェントですぐに有効化できます。正確性、会話の質、カスタマーエクスペリエンス、音声品質に関する、最も一般的な品質の側面を網羅しています。このスキルを使って、有効化する事前定義メトリクスとその設定方法を判断してください。

プラットフォーム上の操作

このスキルで Cekura 上の項目の作成、一覧表示、更新、評価が提案されている場合は、API 呼び出しやダッシュボードの手順を説明するよりも、利用可能なプラットフォームツールを優先して使用してください。Cekura プラグインをインストールした Claude Code では、これらのツールが自動設定され、認証、パラメーターの検証、エラー処理を行います。現在のセッションでツールを利用できない場合に限り、直接 API エンドポイントを呼び出す方法やダッシュボードの操作手順を案内してください。

主な用語

• メインエージェント：テスト対象となるクライアントの AI 音声エージェント
• テストエージェント：メインエージェントを動作させる、Cekura のシミュレーション用発信者
• 事前定義メトリクス：Cekura に付属する組み込み評価器です。プロンプトは不要で、code によって識別されます
• カスタムメトリクス：ユーザーが作成したプロンプトまたは custom_code を持つメトリクスです（cekura-metric-design を参照）
• シミュレーション：Cekura のテストエージェントを使ってメインエージェントをテストする実行（カタログの「Sim」列）
• オブザーバビリティ：エージェントを通じて行われる実際の本番通話（カタログの「Obs」列）
• プロジェクトレベルの切り替え：プロジェクト全体のシミュレーションまたはオブザーバビリティで、事前定義メトリクスを有効にします
• 評価器への追加：特定のテストシナリオにメトリクスを追加します。その評価器でメトリクスを実行するには必須です

事前定義メトリクスとカスタムメトリクス

まず事前定義メトリクスを有効にしてください。プロンプトエンジニアリングは一切不要で、最も一般的な品質の側面を標準で網羅しています。カスタムメトリクスを使うのは、次の場合に限ってください。

• 予約フローやエスカレーション手順など、ビジネス固有のワークフローを評価する必要がある場合
• 独自のシステムプロンプトに照らして、エージェントの動作を確認する必要がある場合
• 複数のシグナルを 1 つのスコアにまとめる必要がある場合

それ以外の場合は、事前定義メトリクスを使えば、信頼性と一貫性のある結果をより迅速に得られます。

事前定義済みメトリクスのワークフロー

1. カタログを確認する — 以下の4つのカタログテーブルを使って、候補となるメトリクスを特定します。Sim／Obs の利用可否、コスト、必須の制約で絞り込みます。
2. 開始時のセットを選ぶ — 以下のベースラインから始めます。より幅広くカバーするには、エージェントの種類（予約、債権回収、サポート、医療、音声品質の調査）ごとの推奨セットが記載された references/selection-by-use-case.md を参照してください。
3. プロジェクトレベルで有効にする — シミュレーションの実行でメトリクスを有効にします（またはオブザーバビリティで有効にします。これらは独立した切り替えです）。これを行わずに評価器へメトリクスを追加しても、何も実行されません。
4. 個々の評価器に追加する — 特定のテストシナリオにメトリクスを紐付け、そのシナリオの実行時に評価されるようにします。
5. 必要に応じて設定する — 6つのメトリクスでは、設定が必要または任意です（無音のしきい値、ドロップオフ／トピックノードのリスト、スペルのカテゴリ、発音の音素）。ペイロードの例は references/configuration-guide.md を参照してください。
6. 実行して検証する — 小規模なバッチを実行して結果を確認します。結果に違和感がある場合は、カスタムメトリクスに頼る前に、以下のよくある落とし穴を確認してください。

API エンドポイント（一覧表示、切り替え、紐付け、設定、再評価）の詳細は、references/api-reference.md を参照してください。

事前定義済みメトリクスを有効にする

2つの手順が必要です。どちらか一方でも欠けていると、メトリクスは実行されません。

1. プロジェクトレベルで有効にする — シミュレーションの実行でメトリクスを有効にします
2. 個々の評価器に追加する — 特定のテストシナリオにメトリクスを紐付けます

GET /test_framework/v1/predefined-metrics/ を使って、利用可能な事前定義済みメトリクスとその ID の全リストを取得します。エージェントのメトリクスセットに追加する際は、事前定義済みメトリクスの code フィールドを渡します。

---

カタログ：精度

メトリクス	出力	コスト	Sim	Obs	備考
期待される結果	0～100 のスコア	無料	✓	—	評価器に expected_outcome_prompt が設定されている必要があります。エージェントがシナリオの目標をどの程度達成したかを採点します。これがない場合、実行結果は通話の完了についてのみ合否判定されます。トランスクリプトのみが対象 — トーン、発音、音声品質などの音声特性は評価できません。プロンプトを作成する際は、話者を「ユーザー」、「アシスタント」、「ボット」、「AI」ではなく、**「メインエージェント」と「テストエージェント」**と呼んでください。
ハルシネーション	True／False	0.6 クレジット	✓	✓	エージェントの応答をナレッジベースと比較し、裏付けのない主張を検出します。
モックツール呼び出し精度	0～100 のスコア	無料	✓	—	適切なモックツールが適切な入力で呼び出されたかを採点します。エージェントにモックツールが設定されている必要があります。
関連性	True／False	0.2 クレジット	✓	✓	エージェントの応答が質問に答えているかを確認します。話題から外れた応答や、はぐらかす応答を検出します。
応答の一貫性	True／False	0.2 クレジット	✓	✓	エージェントが情報を誤って繰り返したり、以前の発言と矛盾したりする場合に、矛盾を検出します。
ツール呼び出しの成功	True／False	無料	✓	✓	いずれかのツール呼び出し結果に「Error」または「failed」が含まれているかを確認します。トランスクリプトにツール呼び出しデータが表示されるよう、プロバイダーとの連携（アシスタント ID と API キー）が必要です。
文字起こしの精度	0～100 のスコア	シミュレーションは無料／本番の通話ログは1分あたり1クレジット	✓	—	本番の通話ログには2つの文字起こしモデルを使用し、実行結果を正解データと比較します。**音声が必要です。**本番の通話ログの評価は高コストのため、必要な場合に限って使用してください。
ボイスメール検出	True／False	0.2 クレジット	✓	✓	通話がボイスメールまたは自動応答システムにつながったかを検出します。ベータ版です。

---

カタログ：会話の品質

指標	出力	コスト	Sim	Obs	備考
AI によるユーザーへの割り込み	回数	無料	✓	✓	エージェントがユーザーに割り込んだ回数を数えます。オブザーバビリティで利用するには、話者ごとにチャンネルが分かれたステレオ音声が必要です。
メインエージェントによる適切な通話終了	True/False	0.2 クレジット	✓	✓	エージェントが通話を早く終了しすぎていないか、またユーザーの懸念が解消されたかを確認します。
テストエージェントによる適切な通話終了	True/False	0.2 クレジット	✓	✓	ユーザー（テストエージェント）が通話を突然終了したかを確認します。これは、体験の質が低い、または問題が未解決であることを示します。
会話中の無音を検出	True/False	無料	✓	✓	どちらの話者も silence_duration 秒を超えて話さなかった場合、False を返します。デフォルト：10s。設定可能です。
インフラストラクチャの問題	True/False	無料	✓	✓	メインエージェントが infra_issues_timeout 秒を超えて無言になった場合、False を返します。「会話中の無音を検出」とは異なり、エージェントに固有の指標です。デフォルト：10s。設定可能です。
割り込みスコア	0～100 のスコア	無料	✓	✓	エージェントがユーザーに割り込む頻度を連続的に評価するスコアです。高いほど割り込みが少なく、品質が高いことを示します。
レイテンシ（ms）	平均 ms	無料	✓	✓	平均応答レイテンシです。P25/P50/P75/P90/P95/P99 のパーセンタイルも報告します。2000ms 未満が良好と見なされます。
ユーザーの割り込み後に停止するまでの時間（ms）	ms	無料	✓	✓	ユーザーが割り込んでからエージェントが話すのをやめるまでの時間です。短いほど応答性が高いことを示します。
不要な繰り返しの回数	回数	0.2 クレジット	✓	✓	エージェントが不要に同じことを繰り返した回数を数えます。
不要な繰り返しスコア	0～100 のスコア	無料	✓	✓	繰り返しの質を連続的に評価するスコアです。高いほど簡潔で、品質が高いことを示します。傾向の追跡には、回数の指標よりこちらを推奨します。
AI へのユーザーの割り込み	回数	無料	✓	✓	顧客がエージェントに割り込んだ回数を数えます。回数が多い場合、不満や会話の順番交代の問題が示唆されます。

---

カタログ：顧客体験

指標	出力	コスト	Sim	Obs	備考
CSAT	0～100 のスコア	0.2 クレジット	✓	✓	顧客満足度の総合評価です。70 を超えるスコアは満足を示します。口調、協力度、問題解決度を評価します。
離脱ノード	Enum	0.2 クレジット	—	✓	通話が終了した会話の段階を特定します。あらかじめ定義した段階名を含む dropoff_nodes の設定が必要です。オブザーバビリティ専用です。
感情	Enum	0.2 クレジット	✓	✓	通話全体の口調や言葉遣いに基づいて、ユーザーの感情を Happy、Angry、Neutral、Disappointed に分類します。
通話のトピック	Enum	0.2 クレジット	—	✓	通話の内容（請求、テクニカルサポートなど）を分類します。topic_nodes の設定が必要です。オブザーバビリティ専用です。

---

カタログ：音声品質

指標	出力	コスト	Sim	Obs	備考
平均ピッチ（Hz）	Hz	無料	✓	✓	通話中のメインエージェントの平均音声ピッチです。音声の一貫性のモニタリングに役立ちます。
意味不明な発話の検出	True/False	0.3 クレジット/分	✓	✓	乱れた、または支離滅裂な発話を検出します。**ステレオ音声が必要です。**ベータ版です。
文字ごとの発音検出	True/False	0.2 クレジット	✓	✓	適切な場面（例：電話番号の確認）で、エージェントが文字を一字ずつ読み上げているかを確認します。spelling_word_types の設定が必要です。
発音チェック	0～100 のスコア	0.2 クレジット	✓	✓	カスタム単語の正確さを確認します。発話された内容を、期待される音素のリストと比較します。**音素ペアとして pronunciation_words の設定が必要です。**ベータ版です。
話速	True/False	0.2 クレジット	✓	✓	エージェントの話すペースの急激な変化を検出します。英語のみです。ベータ版です。
発話比率	0.0～1.0	無料	✓	✓	エージェントの発話時間とユーザーの発話時間の比率です。通常の健全な範囲は 0.4～0.6 です。可観測性の確保にはステレオ音声が必要です。
音声変化の検出	True/False	0.2 クレジット	✓	✓	エージェントの音声が予期せず変化したか（別の話者、音声モデルの問題など）を検出します。ベータ版です。
音声のトーンと明瞭さ	0～100 のスコア	0.2 クレジット	✓	✓	音声品質のスコアです。明瞭さとジッターを分析します。70 を超えるスコアは品質が良好であることを示します。
1 分あたりの単語数（WPM）	WPM	無料	✓	✓	メインエージェントの話す速度です。平均ピッチや発話比率と合わせて、基準値として役立ちます。

---

設定リファレンス

一部の定義済み指標では、設定が必須または任意です。指標の configuration オブジェクトに、キーと値のペアとして指定します。

指標	設定キー	型	デフォルト	説明
会話中の無音を検出	silence_duration	int（秒）	10	どちらかの話者の無音とみなすしきい値
インフラストラクチャの問題	infra_issues_timeout	int（秒）	10	メインエージェントのみを対象とした無音のしきい値
離脱ノード	dropoff_nodes	文字列の配列	必須	会話の段階名（例：["greeting", "verification", "booking", "closing"]）
通話のトピック	topic_nodes	文字列の配列	必須	トピックのカテゴリ（例：["billing", "technical_support", "cancellation"]）
文字ごとの発音	spelling_word_types	文字列の配列	必須	チェックする単語のカテゴリ（例：["phone_number", "confirmation_code"]）
発音チェック	pronunciation_words	オブジェクトの配列	必須	音素ペア：[{"word": "Cekura", "phoneme": "sɛˈkjʊrə"}]

完全なペイロードの例（IPA のヒントと命名に関するガイダンスを含む）については、references/configuration-guide.md を参照してください。

---

コストとクレジットのクイックリファレンス

コスト	指標
無料（0 クレジット）	期待される結果、ツール呼び出しの成功、モックツール呼び出しの正確さ、AI によるユーザーへの割り込み、ユーザーによる AI への割り込み、ユーザーの割り込み後の停止時間、レイテンシ、無音の検出、インフラストラクチャの問題、割り込みスコア、不必要な繰り返しのスコア、平均ピッチ、発話比率、1 分あたりの単語数
1 回あたり 0.2 クレジット	関連性、応答の一貫性、留守番電話の検出、適切な通話終了（両方）、不必要な繰り返し回数、CSAT、離脱ノード、感情、通話のトピック、文字ごとの発音、発音チェック、話速、音声変化の検出、音声のトーンと明瞭さ
1 回あたり 0.6 クレジット	幻覚
0.3 クレジット/分	意味不明な発話の検出
無料（シミュレーション）	文字起こしの正確さ（シミュレーションの実行のみ）
1 クレジット/分（本番の通話ログ）	文字起こしの正確さ（本番の通話ログ評価）

---

ベースライン — 常に有効にする

最低限、すべてのエージェントでシミュレーション用に次の4つを有効にしてください（最後の3つは可観測性にも使用します）。

指標	理由
Expected Outcome	これがないと、実行がわかるのは呼び出しが完了したかどうかだけで、エージェントが実際に正しい処理を行ったかどうかはわかりません
Infrastructure Issues	エージェントが10秒以上応答しなくなる状況を検出します。合否判定では把握できません
Tool Call Success	実際のユーザーに影響が及ぶ前に、連携の不具合を検出します
Latency	パフォーマンス追跡のベースラインです。P95/P99を確認すると、平均値では見えない外れ値がわかります

より充実したベースラインにするには、CSAT、Sentiment、Unnecessary Repetition Score も追加してください。

エージェントの種類別に推奨される指標セット（予約、債権回収、サポート、ヘルスケア、音声品質の調査）については、references/selection-by-use-case.md を参照してください。

---

主な制約

• 音声が必要： Transcription Accuracy と Gibberish Detection には音声データが必要です。テキストのみの実行では利用できません。
• ステレオが必要（可観測性）： AI Interrupting User、User Interrupting AI、Talk Ratio、Gibberish Detection を可観測性の呼び出しで使用するには、話者ごとにチャンネルが分かれたステレオ録音が必要です。
• シミュレーション専用： Transcription Accuracy、Mock Tool Call Accuracy、Expected Outcome。
• 可観測性専用： Dropoff Node、Topic of Call。
• 英語のみ： Speaking Rate。
• 設定が必要： Dropoff Node、Topic of Call、Letterwise Pronunciation Detection、Pronunciation Check は、設定キーを指定しないと有意な結果が得られません。
• プロバイダー連携が必要： Tool Call Success でツール呼び出しデータをトランスクリプトに表示するには、エージェントのプロバイダーアシスタント ID を Cekura に設定する必要があります。

---

よくある落とし穴

• 有効化の両方の手順（プロジェクトの切り替えと評価器への割り当て）を完了せずに指標を有効にする — 指標は利用可能に見えても、実際には実行されません
• Detect Silence と Infrastructure Issues を同じものとして扱う — これらは異なるものを測定します（前者は両方の話者、後者はエージェントのみ）
• 可観測性の呼び出しで Transcription Accuracy を期待する — シミュレーション専用です
• Expected Outcome を使用する際に expected_outcome_prompt を設定し忘れる — これがないと、指標は評価対象を持ちません
• Expected Outcome で音声の特性（トーン、発音、音声品質）を評価しようとする — この指標が参照できるのはトランスクリプトのみです。音声の評価には Speech Quality 指標を使用してください
• expected_outcome_prompt に「user」「assistant」「bot」「AI」などの語句を使用する — Cekura のトランスクリプトにおけるラベルに合わせて、必ず「main agent」と「testing agent」を使用してください
• dropoff_nodes／topic_nodes を設定せずに Dropoff Node または Topic of Call を有効にする — 結果が無意味になります
• モノラル録音で Gibberish Detection を使用する — ステレオ音声が必要です

---

次のステップ

定義済みの指標を選択した後、通常は次の作業が必要です。

• 指標を作成または設定する → 定義済みの指標を補完するカスタム指標には、cekura-metric-design を呼び出します
• パフォーマンスが低い指標を改善する → フィードバックとラボのサイクルには、cekura-metric-improvement を呼び出します
• テストシナリオに指標を割り当てる → 評価器で指標を連携するには、cekura-eval-design を呼び出します

ドキュメント

• 定義済み指標のリファレンス：https://docs.cekura.ai/documentation/key-concepts/metrics/pre-defined-metrics
• 公開ドキュメント：https://docs.cekura.ai
• 概念：https://docs.cekura.ai/documentation/key-concepts/

追加リソース

参照ファイル（必要に応じて読み込み）

• references/configuration-guide.md — 設定可能な各定義済み指標の完全なペイロード例（無音のしきい値、ドロップオフ／トピックノードのリスト、スペルのカテゴリ、IPA の音素ペア）
• references/api-reference.md — 定義済み指標の一覧表示、切り替え、添付、設定、再評価を行うための公開 API エンドポイントと、エンドツーエンドのフロー例
• references/selection-by-use-case.md — エージェントの種類（予約、債権回収、カスタマーサポート、医療、音声品質の調査）ごとに推奨される定義済み指標セット