cekura-flag-call-log-failures

flag-call-log-failures

エージェントの最近の本番通話ログを確認し、次の3つを作成します。

1. フラグ付き通話 — 指定された各KPI／問題／目標の未達に該当した通話IDと、そのことを示す逐語的な証拠。
2. 失敗率 — 確認した全通話ログに占める割合として、各失敗が何％にあたるか。
3. 結果の分布 — 残りの通話を、相互排他的な結果分類（例：未応答／審査完了／未審査 — 発信者側／未審査 — エージェント側の問題）に分類し、各分類の割合を示します。これにより、フラグ付きの失敗を全体の中に位置づけます。

これはトリアージのフロントエンドです。フラグ付きの通話を cekura-generate-scenarios に渡して評価器を作成するか、顧客向けの品質レポートでユーザーに分布を提示します。

このスキルは完全な読み取り専用です。作成、更新、削除は一切行いません。

最も重要な役割は原因の特定です。通話がエージェントの失敗となるのは、テスト対象のエージェントが原因の場合に限ります。発信者側による終了、シミュレーション上の発信者による切断、回復した通話は、エージェントの失敗として数えてはいけません。それぞれ別の分類に含めます。

---

ステップ 0 — 前提条件

Cekura MCP を通じて読み取ります。次のツールが利用可能であることを確認してください。

• mcp__cekura__aiagents_retrieve — エージェントの説明と想定される動作（「失敗」を判断する基準）
• mcp__cekura__call_logs_list — ページネーションされた本番通話の一覧（軽量で、通常は id、duration、call_ended_reason、success、集計済みの指標スコアが含まれますが、トランスクリプトは含まれないことがよくあります）
• mcp__cekura__call_logs_retrieve — 個別の通話の完全なトランスクリプトと指標の評価
• mcp__cekura__metrics_list — KPI／問題をすでに評価している指標を探すために使用します（該当する指標がある場合は、分類の基準として再利用します）

mcp__cekura__* ツールが接続されていない場合は、処理を中断して、Cekura MCP を接続するようユーザーに伝えてください（/setup-mcp または https://docs.cekura.ai/mcp/overview を参照）。

---

ステップ 1 — 入力

指定されていない項目は、AskUserQuestion を使って確認します。

1. エージェント ID（数値）。不明な場合は、mcp__cekura__aiagents_list で検索できます。

2. （任意）プロジェクト ID。

3. 対象期間 — 最近の通話数（デフォルトは 100 件）または日付範囲。処理はバッチ単位で行います（ステップ 2 を参照）。

4. 測定するKPI／問題／目標 — 依頼の中心となる項目です。

   • 明示された問題 — 例：「すべての審査質問を終える前に終了した通話」、「不明瞭な回答に対してエージェントが同じ応答を繰り返した」、「バックグラウンドノイズでエージェントの処理が滞った」。それぞれにフラグの分類と失敗率を設定します。
   • KPI／目標 — 例：「すべての通話で候補者の審査を完全に行う」、「回答済みの通話のうち、何％を改善できるか」。目標の未達につながる失敗を逆算します。
   • 具体的な指定がない場合 → agent_description を根拠に、ステップ 3 の失敗モード分類に基づいて「真のエージェントの失敗」を分類します。

5. 結果分類 — すべての通話を振り分ける、相互排他的な分類を指定します。エージェントの役割から導き出してください。候補者審査エージェントの場合、自然な分類は次のとおりです。

   • 未応答 · 審査完了 · 未審査 — 発信者側 · 未審査 — エージェント／システムの問題

   その他のエージェントでは、役割に応じて調整してください（例：解決済み／エスカレーション済み／放棄／エージェントエラー）。報告を行う前に、分類の組み合わせをユーザーに確認してください。

処理を進める前に、問題の一覧と分類の組み合わせをユーザーに示し、確認を取ってください。

---

ステップ 2 — バッチで取得し、低コストの分類から始める

エージェントのコンテキスト — mcp__cekura__aiagents_retrieve(id=...)：agent_description、agent_name、project_id、および KPI を定義する {{dynamic_variable}} 名（例：requiredScreeningQuestions）を取得します。

⚠️ agent_description が空またはプレースホルダーで、明示的な問題リストも指定されていない場合は、そこで停止してください。「失敗」の根拠がありません。問題を挙げるか、説明を詳しくするようユーザーに依頼してください。

通話ログ — バッチで繰り返し取得します。 page_size=20 を指定して mcp__cekura__call_logs_list を呼び出し、対象期間を網羅するまで page=1..K を順に取得します。リスト表示は軽量なので、まずすべての通話について、低コストで確認できる情報を集めます。

フィールド	用途
id、duration	識別、長さに基づくヒューリスティクス
call_ended_reason	誰が／何が通話を終了したか（最初の判定で最も強いシグナル）
success / status	集計された合格／不合格
metrics[] スコア	KPI メトリクスがすでに実行されている場合（下記参照）、スコアを直接確認します

低コストの初回判定（ヒューリスティクス）→ 候補のみ検証します。 すべての文字起こしを取得するのは無駄が多く、トークンの予算を超えるおそれがあります。代わりに、次のようにします。

1. まず call_ended_reason と duration で分類します。 有力な指標：
   • 非常に短い（例：< 25s）→ 応答なし／エンゲージメントなし
   • エージェントが終了（Main agent-ended-call）し、通常の長さ → エージェントがフローを完了（暫定的に審査済み）
   • 発信者／テストエージェントが終了（testing-agent-ended-call、customer-ended-call、Client disconnected）→ 発信者側（暫定）
   • 無音／タイムアウト（Ending conversation after N seconds of silence）→ エージェント／システム側の候補（要検証）
2. エージェント起因の問題の候補のみ、文字起こしで検証します — 無音によるタイムアウト、異常に長い通話、ヒューリスティクスで分類できない通話が対象です。これらは call_logs_retrieve で取得します（大きい場合はファイルに出力されます。インラインで読むのではなく、スクリプトでループ／繰り返しを検出してください）。
3. 「長い通話 ≠ ループ」です。 長い通話だからといって、自動的にエージェントの失敗とは限りません。集計する前に検証してください。実際に同じ質問が繰り返されている（正規化した同一のエージェント発話が 4 回以上）か、質問を次々と作り出してしまうパターンがあるかを確認します。多くの長い通話は、審査が丁寧なだけです（エージェントと候補者のターンがほぼ 1:1 で、繰り返しはありません）。

分類の基準には、すでに作成済みのメトリクスを優先してください。 エージェント／プロジェクトに関連付けられているメトリクスには、正確な帰属ルールが反映されています。

• Call not answered (no pickup / voicemail) → 応答なしの分類を定義します（TRUE = 応答なし）。
• All vetting questions asked (perf) → 対象となる通話での審査完了を示します（PASS = 審査済み）。
• Testing agent ended call before hard vetting started → 発信者側の早期離脱を示します（TRUE）。
• All vetting questions asked（失敗フラグ）→ エージェントによる質問の省略を示します。

対象期間についてこれらのメトリクスがまだ評価されていない場合は、監査対象の件数について call_logs_evaluate_metrics_create を実行して評価できます（評価クレジットが必要で、非同期です）。または、文字起こし／ヒューリスティクスで分類し、結果が推定値であることを報告してください（どちらを用いたか明記してください）。

call_logs_list の結果が 0 件の場合は停止してください。本番前のエージェントであり、トリアージ対象はありません。

---

ステップ 3 — 各通話を分類する

各通話について、結果バケット（相互排他的）を決めます。エージェントの失敗に該当する場合は、どの問題／モードかも判断します。失敗としてフラグを立てる場合は、次を記録します。

{ call_log_id, issue/mode, severity, evidence_quote, ended_reason, expected_behavior }

• evidence_quote — トランスクリプトの該当箇所（または失敗を示す指標の根拠）を一字一句そのまま記載します。言い換えは禁止です。引用できない場合は、フラグを立ててはいけません。
• expected_behavior — エージェントがどう対応すべきだったかを1文で記述します（シナリオの expected_outcome_prompt に引き継がれます）。

「実際の失敗」に該当する場合の分類（問題リストが明示されていない場合）：

コード	モード	検出シグナル
🛑 drop	エージェントによる早期終了	エージェントがワークフローの途中で終了／転送した、エージェント側の切断
🌀 drift	話題／ペルソナからの逸脱	agent_description と無関係な内容
👻 hallucination	KB／説明にない事実	説明／KB に記載のない数値／ポリシー／製品
🔧 tool_error	ツール選択／引数／ツール実行後の問題	ツールエラー、ツールがすでに回答した内容を再度質問する、誤ったツール
🎯 workflow_miss	必須手順の省略／誤り	必須質問をすべてする前に結論を出した、同意を得ずに進めた
🤔 comprehension	ユーザーの意図の誤解	同じ確認質問を3回以上繰り返す、回復できないままループする
🔁 loop	行き詰まり、いつまでも収束しない	同じ質問／確認を何度も繰り返す、質問を次々と作り出して暴走する
🚪 refusal	正当で範囲内の依頼を拒否	説明の範囲内で「対応できません」と拒否する
⚡ latency	長い間隔／応答の遅さ／無応答	発話間の間隔が長い、ユーザーが話し終えた後に応答しない
🧨 safety	PII の漏えい／危険な内容	求められていないのに SSN／カード番号を繰り返す、禁止されている内容
📻 asr_capture	候補者が話したが認識されなかった	候補者の発話が「…」として記録される。エージェントが「まだいらっしゃいますか？」と再度促し、その後無音タイムアウトになる（システム／ASR の分類。改善の余地はありますが、プロンプトの不具合ではありません。個別に指摘してください）

1つの通話で複数の問題が発生する場合があります。それぞれを記録してください。ただし、結果バケットは必ず1つだけです。

---

ステップ 3.5 — 原因の特定と復旧に関するルール（誤検出を防止）

**テスト対象のエージェントが原因の場合に限り、エージェントの失敗として扱います。**それ以外は、エージェント以外のバケットに分類します。

1. ユーザー側／シミュレーションユーザー側による終了は、エージェントの失敗ではありません。 エージェントが完了する前に call_ended_reason が {testing-agent-ended-call, customer-ended-call, Client disconnected: 1005/1012} のいずれかになった場合は、エージェントの失敗ではなく、未審査のユーザー側終了です。
2. 復旧できた場合は失敗ではありません。 エージェントが一時的につまずいても、必要な情報を得て処理を続けた場合はフラグを立てません。行き詰まったまま／復旧できない／通話が脱線した場合に限り、フラグを立てます。
3. 正当な早期終了は失敗ではありません。 候補者が辞退した、必須条件を満たさなかった、または折り返しを希望したために正しく終了した場合は、適切な対応です。失敗ではなく、クリーンな結果／正当な結果として扱います。
4. エージェントがユーザーの発話に割り込む／発話を遮る行為は、デフォルトではフラグを立てません — ユーザーが明示的に指摘している場合に限ります。

ユーザーが明示した問題リストがデフォルトのルールと矛盾する場合（例：ユーザー側の切断も対象にしたい場合）は、ユーザーの指示に従ってください。

---

Step 4 — 定量化して共有する

レビュー済みの全件を対象に、次の2つを計算します（N = レビュー済みの合計件数）。

A. 失敗率。 フラグを付けた各問題について、count / N = その失敗が発生した全通話ログに占める割合。ユーザーが「応答済みの通話のうち何％」と指定した場合は、応答済みの分母を使って計算します（応答済み = N − not_answered。not-answered は Call not answered のバケットです）。分母を明記してください。

B. 結果の分布。 各通話を必ず1つのバケットに割り当て、件数と割合を報告します。

not answered            : a/N
vetted                  : b/N   (= b/answered)
non-vetted caller-side  : c/N   (= c/answered)
non-vetted agent/system : d/N   (= d/answered)   ← the improvable slice

有用な場合は、バケットをさらに細分化します（エージェント／システム側の内訳は、多くの場合、ASR-capture と true agent loop などに分かれます。発信者側の内訳は、dropped before vetting began と dropped mid-vetting に分かれます。後者は Testing agent ended before hard vetting started の指標に対応します）。

改善可能な数値を見出しにします。 「応答済みの通話のうちX%は、こちら側で改善できます」（エージェント／システムのバケット）と示し、未審査件数のうち発信者側の割合（エージェントの不具合ではないこと）を記載します。

---

Step 5 — 報告する

# Call-log failure analysis — <agent_name> (`<agent_id>`)

**Window:** last <N> calls (<start> → <end>) · **Answered:** <A>
**Criteria:** <the confirmed KPI/issue list>

## Outcome distribution
| Bucket | Count | % of all | % of answered |
|---|---|---|---|
| Not answered | a | a/N | — |
| Vetted | b | b/N | b/A |
| Non-vetted — caller-side | c | c/N | c/A |
| Non-vetted — agent/system (improvable) | d | d/N | d/A |

→ **~d/A% of answered calls are improvable on our side.** (Caller-side = c/A%, not an agent defect.)

## Flagged failures (agent/system) — call IDs + rate
| Issue | Rate (of all) | Calls (evidence) |
|---|---|---|
| ASR capture → silence drop | 6/N | [<id>](…) "are you still there?" ×N → timeout; … |
| Loop | 1/N | [<id>](…) re-asked "which shift?" ×6 |

## Methodology & confidence
- Which calls were transcript-verified vs. heuristic-bucketed (ended_reason + duration).
- If the agent/system count is a lower bound (issues hidden inside agent-ended/caller-ended calls weren't all read), say so.
- Whether numbers are audited (metrics evaluated) or estimated (heuristic).

ルール：

• 通話への参照はすべて、https://dashboard.cekura.ai/<project>/observe/<id> への Markdown リンクにします。
• 根拠は一字一句そのままの引用にします（「11問中7問」などの短い注釈を添えてもかまいません）。
• フラグを付けたエージェント／システム側の通話は明示的に列挙します。件数の多い問題のないバケットは、クリーンな ID を列挙せず、件数のみを記載します。
• 直接的で、根拠に基づくトーンにします。すべての割合について分母を明記してください。

---

Step 6 — 引き継ぐ

フラグを付けたエージェント／システム側の通話は件（応答済みの件中<d/A>%）です。これらを回帰シナリオに変換しましょうか？cekura-generate-scenarios にフラグ付きのセットを渡せます。このツールが通話をクラスタリングし、失敗パターンごとに評価器を1つ作成します。

はいの場合は、cekura-generate-scenarios を呼び出して、フラグ付きのセットを渡します。各エントリには {call_log_id, issue/mode, severity, evidence_quote, expected_behavior} がすでに含まれており、ツールが必要とする通話ごとのレコードがそろっています（独自のマイニングはスキップし、すぐにクラスタリングを開始します）。そこで再度トリアージしないでください。

---

停止／リダイレクトする場合

• 既知の単一通話 → シナリオ： トリアージをスキップし、直接 cekura-generate-scenarios を呼び出します（単一通話の高速処理）。
• 1回の実行が失敗した理由（電話、接続できなかった、SIP、文字起こしが空）→ これは実行のデバッグであり、通話ログのトリアージではありません。実行時の電話／エージェント設定を調査するか、Cekura サポートに問い合わせてください。
• 本番の通話ログがない（本番前のエージェント）→ 停止します。トリアージ対象はありません。