cxas-cuj-report-generator

クリティカルユーザージャーニー（CUJ）トランスクリプトおよびレポート生成スキル

顧客要件ドキュメント（図、BRD、コードなど）のディレクトリから、対話のトランスクリプトを抽出したり、インタラクティブなクリティカルユーザージャーニー（CUJ）レポートを作成したりするよう依頼された場合に、このスキルを使用します。

コアプロトコル

網羅率を100％にし、データ損失をゼロにするため、以下のコアルールに必ず従ってください。

• 堅牢な抽出：cxas-protocol-robust-extraction スキルで定義されているプロトコルに従ってください。
• 2段階の取り込み：protocols/cxas-protocol-two-phase-ingestion/ 内の cxas-protocol-two-phase-ingestion サブプロトコルで定義されているプロトコルに従ってください。
• チェックリストの必須使用：オーケストレーターとすべてのサブエージェントは、agent-protocol-checklist プロトコルに従って、ローカルの task_checklist.json ファイルを管理し、実行中の進捗を追跡して網羅性を損なわないようにしなければなりません。
• オーケストレーターによる納品の保証：オーケストレーターは、厳格で独立した納品監査担当者として行動しなければなりません。サブエージェントを終了し、ウォッチドッグを停止するか、キャンペーンの成功をユーザーに報告する前に、オーケストレーターは登録済みのすべての成果物（特に gecx_customer_report.html および gecx_cuj_report.html）について、ディスク上での存在、サイズの範囲、スキーマへの準拠を実際に確認しなければなりません。いかなる場合も、実際にファイルの存在を確認せずに、完了したと判断してはなりません。
• 監査：オーケストレーターはサブエージェントのスクラッチディレクトリを定期的に確認し、task_checklist.json ファイルが作成・更新されていることを確かめなければなりません。ファイルが存在しない、または更新されていない場合、オーケストレーターはそのサブエージェントを終了し、より厳格な指示を与えて再起動しなければなりません。

コアワークフローの手順

タスクを実行するには、次の5段階の構造化されたワークフローに従ってください。

1. スコープ設定とタイプの特定：環境を準備し、必要なスキルを特定します。

   • ファイルへのアクセス：ローカルワークスペース内のソース成果物にアクセスできることを確認します。

     • ヒント（Drive リンク）：ソースが Google Drive のリンクまたはフォルダー ID の場合、必ず gdrive スキルを使用してアクセスしてください。

   • インベントリタイプの検出：フレームワークのシグネチャを特定し、適切なインジェスターに対応付けるには、agents/framework_detector.md で定義されているフレームワーク検出エージェントを必ず使用してください。このエージェントを使って入力ファイルをスキャンし、すべてのファイル拡張子を一覧化して、該当する可能性のあるフレームワークを検出します。ファイルツリーを分割し、並列でスキャンする Framework Detector サブエージェントを起動してください。

   • インジェスターの対応付け：Framework Detector が作成したスコープ設定レポートを使って、ingestors/frameworks/ または ingestors/files/ 内から適切な専用スキルを選択するか、作成してください。

     • 優先順位ルール：フレームワーク固有のインジェスターは、汎用のファイル拡張子インジェスターより優先されます（例：両方が適用できる場合は、ingestors/files/py/ ではなく ingestors/frameworks/adk/ を使用します）。

2. 調査：特定したタイプに基づいて、専用のエキスパートサブエージェントを起動し、サブインテントを特定します（役割の定義については agents/ ディレクトリを参照してください）。ingestors/frameworks/ および ingestors/files/ 内の専用インジェスタースキルを動的に特定し、使用します。

   • 必須の引き継ぎ：サブエージェントは、以下を必ず報告しなければなりません。

     1. 検出したフレームワーク
     2. 解析したファイルタイプ
     3. スコープ外としてスキップしたファイルやパターン

   • 網羅的な使用：各ファイルに適用できる最も具体的なインジェスターを使い、該当するインジェスターをすべて使用してください。

   • フォールバック：スコープ外のファイルタイプに対応する専用インジェスターが存在しない場合、オーケストレーターは分析を委任しなければなりません。

     1. アナライザーの起動：専門の分析サブエージェントを起動し、不明なファイルのサンプルを調査します。
     2. 調査：構造が明確でない場合は、形式の標準をオンラインまたは内部ドキュメントで検索するようサブエージェントに指示します。
     3. 報告と形式化：サブエージェントは、最適な解析戦略をオーケストレーターに報告し、この知識を記録するために ingestors/frameworks/ または ingestors/files/ に新しい専門スキルを作成することを試みるべきです。

3. 枯渇：新しいインテントが見つからなくなるまで繰り返します。

4. クラスタリング：親 CUJ にグループ化します。一貫性と正確性のあるカテゴリの検出を実現するには、次の点に従います。

   • ノイズの低減：生の文字起こしやコードを含む完全なオブジェクトを渡さないでください。
   • 要約形式：id、技術タグを取り除いた name、および1文でまとめた intent を含む、整形済みの YAML リストを指定します。
   • ガイダンス：妥当なカテゴリ数は通常5～10であるとエージェントに伝えます。

5. 実行：このディレクトリ内のツールを使って、文字起こしとレポートを生成します。

   • 必須：LLM のコンテキスト枯渇や切り捨てを防ぐため、サブエージェントごとのバッチサイズを5～10項目に制限します。
   • タイトルの作成：各文字起こしについて、エージェントは会話の内容と CUJ のタイトルを基に、短く人が読みやすいシナリオタイトルを必ず作成し、生の技術 ID の代わりに subintent_name フィールドに保存します。
   • ID の即時検証：口座番号や注文 ID などの機密性の高い番号は、ユーザーが提示した直後にバックエンドシステムで確認されると常に想定し、それに応じて webhook_call または tool_call を挿入します。
   • エージェント優先の文字起こし：すべての文字起こしは例外なく、標準の歓迎の挨拶から始める必要があります。挨拶は "Hello! Thanks for calling [Brand]. How can I help you today?" とし、ブランドが指定されていない場合は "Hello! Thanks for calling. How can I help you today?" などの一般的な歓迎の挨拶を使います。元の要件で別の名前が示されていても、別の表現は一切認められません。
   • 音声のリアリティ（URL を読み上げない）：音声チャネルのエージェントは長い URL を読み上げられません。エージェントの発話に生の URL（例：https://...）を記述してはいけません。代わりに、リンクをテキストメッセージまたはメールで送ることを口頭で伝えます（例："追跡リンクをお客様の電話にテキストメッセージで送りました"）。
   • セッション終了の標準化：すべての会話は、次の3ターンから成る構造化された別れのやり取りで締めくくる必要があります。
     1. エージェント："本日、ほかにお手伝いできることはありますか？"
     2. ユーザー："いいえ、以上です。ありがとうございます。"
     3. エージェント："お電話いただきありがとうございました、[Brand]！さようなら。"（または "カスタマーサポートにお電話いただきありがとうございました！さようなら。" など、ブランドに応じた別れの挨拶。ブランドが指定されていない場合は "お電話いただきありがとうございました！さようなら。"）とし、別の表現は一切認められません。最後のエージェントのターンでは、必ず end_session システムツール呼び出しを実行します。いかなる場合も、このツール呼び出しを省略してはいけません。次の CXAS スキーマに一致させてください：yaml tool_call: name: end_session payload: session_escalated: false reason: "Conversation completed successfully" response: result: "success"
   • 2種類のレポート：エージェントは CUJ レポート（例は最大3件）と、包括的な完全レポート（すべての例を含む）の両方を必ず生成します。
   • 使用方法：CUJ レポートを生成するには construct_report.py を --cuj_report=True で実行し、包括的な完全レポートを生成するには --cuj_report=False で実行します。

自律実行のガードレール

デフォルトでは、このワークフローは長時間実行され、自律的な実行が必要です。 以下のガードレールに必ず従ってください。

1. 自動ウォッチドッグ：タスクの開始時に、schedule ツールを使って 5 分ごとなど、定期的なタイマーを必ず自動で設定し、停止しているサブエージェントやタスクがないか確認してください。
2. 初回の確認：ユーザーへの最初の応答では、Robust Extraction Protocol を適用していること、およびウォッチドッグタイマーを設定したことを明示してください。
3. 動的な二分割：不足項目が原因でバッチが Verification Gate に 2 回失敗した場合、バッチを自動的に二分割し、負荷を減らした 2 つの処理を担当するサブエージェントを並行して起動してください。

コアスキーマ

生成するすべてのトランスクリプトは、 resources/schemas/transcript_schema.yml の契約に準拠する必要があります。

• subintent_id：一意のスラッグ。
• subintent_name：人が読める名前。
• parent_cuj：上位カテゴリ。
• turns：対話オブジェクトのリスト。

対話ターンの要件

• 話者：Agent または User のいずれかでなければなりません。関数呼び出しのターンは、必ずユーザーのターンの直後に配置してください。
• **テキスト：**実際に発話された文字列。
• ルートレベルの呼び出しフィールド：tool_call（end_session など）と webhook_call のフィールドは、YAML トランスクリプト内の個々のターンオブジェクトのルートレベルに記述する必要があり、enrichment やその他の親キーの下にネストしてはなりません。
• エンリッチメント：
  • intent_detected：該当する場合、NLU インテントを指定します。
  • tool_call：エージェントがローカル関数を呼び出す場合に使用します。
  • webhook_call：エージェントが外部 API を呼び出す場合に使用します。
  • system_action：状態遷移やバックグラウンドロジックに使用します。

言語と音声の自然さに関する基準

生成されるすべての音声対話ターン（Agent の音声ターン）は、高い忠実度の音声基準に厳密に従う必要があります。サブエージェントは、次の点を必ず守ってください。

1. 数値の音声表記への正規化：Agent の発話ターンには、数字のままの数値、書式設定された通貨、または数値を表す句読記号を含めてはなりません（例："450"、"$909"、"555-0199" と書いてはいけません）。代わりに、数値は発音どおりに明示的に綴ってください。
   • 正しい例："四百五十ポイント"、"九百九ドル"。
   • ID、時刻、注文番号、割合、電話番号：数値 ID、時刻、数量、リワードポイント、割合など、あらゆる数値は、句読点やコロンで区切らず、一桁ずつ、または単語ごとに発音どおりに記述する必要があります："五 五 五、ゼロ、一、九、九"、"午後七時三十分"、"午後八時"、"注文番号 九 九 八 八"、"二十パーセント割引"。
   • スケジュール確認：予約や配達状況について、具体的な時刻、期間、予約日を設定したり伝えたりする場合（例：「二十分後に準備ができます」「十分後に到着します」「明日の午後八時に予約しました」）、ユーザーに明示的に確認してください（例：「よろしいですか？」「ご都合はいかがですか？」「この内容で進めてもよろしいですか？」）。
2. 発話の息継ぎの長さの制限：Agent のターンは簡潔で、自然な会話調にしてください。個々の発話テキストブロックは、1 つのターン内で 300 文字を超えてはなりません。
3. 語彙のなめらかさ：同じ長い単語を機械的に繰り返すことは避けてください（1 つのターン内で、5 文字以上の同じ単語を 4 回を超えて繰り返してはいけません）。
4. 会話における丁寧さ：ユーザーに温かく自然な体験を提供するため、Agent の発話ターンには、標準的な丁寧表現を少なくとも 1 つ含めてください（please、thank you、thanks、certainly、happy to help、welcome、goodbye、great day、my pleasure、certainly help）。

実行フェーズの詳細

実行フェーズ中、サブエージェントはトランスクリプトファイルに直接書き込んではなりません。

1. 1ターン分のデータを含む小さな YAML ファイルを生成します。
2. append_turn.py スクリプトに渡して、トランスクリプトを段階的に作成します。
3. すべてのバッチの検証が完了したら、construct_report.py を実行して、最終的なインタラクティブ HTML レポートを生成します。

サブエージェントへの必須指示：バッチ実行のためにサブエージェントを起動する際、オーケストレーターはプロンプトに次の指示を含める必要があります。

「すべてのターンで append_turn.py を使用してください。対話を要約しないでください。 バッチ内の各項目について、自然で完全な会話を生成してください。」