cxas-loss-analysis

Insights の損失分析とレポート生成

このスキルでは、最近の会話を CCAI Insights から取得し、エスカレーションされた／解決に至らなかったセッション（損失）を特定し、根本原因を分析して失敗パターンに分類し、プロフェッショナルな Markdown レポートを作成します。

---

実行手順

以下の手順を正確な順序で実行します。

ステップ 1：パラメータの確認

ユーザーが次の必須パラメータを指定していることを確認します。

• project_id：Insights をホストする GCP プロジェクト ID。
• location：Insights のロケーション（例：us）。
• app_id：対象の CXAS アプリ ID（例：db9ee866-28db-458b-b835-78137c974779）。
• output_dir：最終レポートとテストケースの保存先ディレクトリ。

分析の対象範囲を指定する場合は、次の任意パラメータも確認します。

• start_time：期間の開始を示す RFC 3339 タイムスタンプ（例：2026-05-20T00:00:00Z）。
• end_time：期間の終了を示す RFC 3339 タイムスタンプ（例：2026-05-26T23:59:59Z）。
• filter：適用するカスタム API フィルター文字列（デフォルトの損失フィルター -labels.sessionContained="true" を上書きします）。
• limit：取得して処理する会話の最大数（デフォルト：500）。

ステップ 2：損失トランスクリプトの抽出

軽量なデータ抽出スクリプトを実行し、損失トランスクリプトを分割した JSON ファイルとしてワークスペースに出力します。

コマンドテンプレート：

python3 -P .agents/skills/cxas-loss-analysis/scripts/fetch_losses.py \
  --project-id "{project_id}" \
  --location "{location}" \
  --app-id "{app_id}" \
  --limit {limit} \
  --output-file "{output_dir}/raw_losses.json" \
  [--start-time "{start_time}"] \
  [--end-time "{end_time}"] \
  [--filter "{filter}"]

注：パスの汚染を避けるため、必ず仮想環境の実行ファイルを -P フラグ付きで使用して Python を実行してください（例：.venv/bin/python -P）。

ステップ 3：トランスクリプトの読み取りとエスカレーションの要約

view_file またはその他のファイル読み取りツールを使用して、生成された {output_dir}/raw_losses.json ファイルを読み取ります。分割された JSON ファイルへのパスを含む chunks のリストを抽出します。

chunks リスト内の各チャンクファイルについて：

1. チャンクファイルを読み取り、トランスクリプトのバッチを読み込みます。
2. 各会話のトランスクリプトについて： a. 顧客（user）と仮想エージェント（agent）の会話を分析します。 b. ユーザーに 「AI 嫌悪」 が見られるかを特定します。
   • 定義：ユーザーがエージェントと実質的なやり取りをしなかったセッション、または人間のエージェントを強く希望したセッションです（例：問題を説明せずに最初の 1～2 往復で「人間」「エージェント」「担当者」をすぐに求める、または AI／ロボットとは話したくないとはっきり述べる）。
   • 「AI 嫌悪」が検出された場合、このセッションをコア損失分析の対象から除外します。理由を記録します（例：「AI 嫌悪：ユーザーがすぐに人間のエージェントを要求した」）。 c. 除外対象ではない実際の損失について：
   • 会話がエスカレーションされた理由、または解決に至らなかった理由を特定します。
   • 失敗／エスカレーションの主な理由を簡潔な 1 文で作成します（最大 20 語）。 例：「仮想エージェントは、PIN の入力エラーが繰り返されたためユーザーを認証できなかった。」

ステップ 4：失敗を損失パターンに分類

ステップ 3 で作成した、実際の失敗理由（除外対象ではないもの）の全リストを確認します。分析能力を活用し、これらの失敗理由を相互に排他的な 8～10 個の異なる失敗パターンにグループ化して、詳細な分析結果を提供します。

各パターンについて、次の項目を定義します。

1. パターン ID：シンプルなキー（例：pattern_1、pattern_2、...）。
2. 名前：短く、内容が伝わる名前（例：「認証ループ」、「未対応の顧客の意図」、「意図の明確化時のエージェントへの転送」）。
3. 説明：パターンと発生のきっかけを説明する、明確な 1～2 文。

ステップ 5：すべてのセッションを分類

分析したすべての conversation_id を、次のいずれかに対応付けます。

• 定義した 8～10 個の失敗パターンのいずれか。
• ユーザーに AI 嫌悪が見られた場合は ignored_ai_aversion。

最終レポート用に、この対応付けを記録しておきます。

ステップ 6：Markdown レポートの作成

分析結果を構造化された Markdown レポートにまとめ、{output_dir}/loss_patterns_report.md に書き込みます。次の構成を使用します。

# Loss Patterns Analysis Report

**Project**: `{project_id}`
**App ID**: `{app_id}`

## Executive Summary

A sample of up to {limit} conversations matching the filter was selected for detailed manual analysis and clustering to identify key patterns.

## Loss Patterns Distribution

| Pattern ID | Name | Count | Percentage of Genuine Losses |
| --- | --- | --- | --- |
| `pattern_1` | Pattern Name | Count | Pct% |
| ... | ... | ... | ... |

*Note: Ignored AI aversion sessions are excluded from the pattern distribution.*

## Detailed Patterns Breakdown

### `pattern_1`: Pattern Name

**Description**: Pattern description.
**Total Conversations**: Count

#### Examples & Failure Reasons:
- **Session `{conversation_id_1}`**: Failure reason from Step 3.
- **Session `{conversation_id_2}`**: Failure reason from Step 3.

---

## Appendix: Ignored Sessions (AI Aversion)
The following sessions were ignored from the pattern analysis because the user displayed AI aversion:
- **Session `{conversation_id_3}`**: AI aversion reason (e.g., *"User demanded human agent immediately"*).
- **Session `{conversation_id_4}`**: AI aversion reason.

ステップ 7：概要をユーザーに提示する

調査結果の明確な概要をチャットに直接提示し、{output_dir}/loss_patterns_report.md を案内するとともに、主なパターンと調整後の封じ込め率を強調してください。