agentforce-d360-analyze

agentforce-d360-analyze — Data Cloud 360° セッションビュー

1 つの Agentforce セッションについて、Data Cloud STDM + GenAI DMO から階層的にセッションを再構成します。3 つのステージ（取得 → 組み立て → 表示）で構成されます。標準的な所要時間は、約 15 ターンのセッションで約 10～30 秒です。

このパイプラインは DC 専用 です。Data Cloud によってマテリアライズされたランタイム監査行を読み取ります。ランタイムの可用性を調べるツールではありません。このスキルで回答できない内容については、下記の「DC 専用の盲点」を参照してください。

続行に必要な情報がユーザーから与えられていない場合

セッション ID も検出条件も指定せずに呼び出された場合は、このブロックをそのまま出力してください。言い換えたり、スクリプトを事前に実行したりしないでください。トリガー条件：入力が空、またはセッション ID の形式（UUID も 0Mw… メッセージ ID も）がなく、検出条件（時間表現／--agent／--channel／--outcome／--grep／「検索」「一覧表示」などの動詞）もない場合。

Data Cloud からどのセッションを取得しますか？ また、どの組織ですか？

次の情報が必要です。

• セッション ID — Agent Session UUID（019db7f6-…）または MessagingSession ID（0Mw…、15/18 文字）のいずれか。
  • セッション ID がありませんか？ — 覚えている情報を教えてください。こちらで検索します。どれくらい最近か（例：「直近 2 時間」「今日」、日付）、エージェント、チャネル（Messaging / Builder / Voice）、終了方法（エスカレーション、ユーザーによる終了、転送、タイムアウト）、会話中のフレーズなどです。一致するセッションを番号付きリストで表示しますので、1 つ選んでください。そのセッションを取得します。
• Org alias — sf CLI 認証用のエイリアス（sf org login で設定したもの）。

成果物は ~/.vibe/data/agentforce-d360-analyze/<org_id15>/<agent>__<ver>/<session_id>/ に保存されます（スクリプトごとに --data-dir <path> で上書きできます）。

セッション ID の形式 — UUID または MessagingSession ID

--session では、どちらの形式も使用できます。

形式	例	解決方法
Agent Session UUID	019dface-0000-7000-8000-000000000002	そのまま渡します
MessagingSession ID（0Mw プレフィックス）	0MwTESTMSG12345AAA	resolve_session.py で解決します。初回の取得時は Data Cloud をライブ検索し、以降はディスクを優先します

複数件に一致することがあります。 1 つの MessagingSession ID が複数の Agent Session UUID に対応する場合があります。複数件に一致した場合、リゾルバーはすべての候補を出力して、ゼロ以外の終了コードで終了します。ユーザーは特定の UUID を指定して再実行します。

成果物は常に ~/.vibe/data/agentforce-d360-analyze/<org_id15>/<agent>__<ver>/<session_id>/ に保存されます（デフォルト。スクリプトごとに --data-dir <path> で上書き可能）。メッセージ ID は検索キーとしてのみ使用され、ディレクトリ名にはなりません。主要なエージェント（sorted(agents_observed) の先頭）が <agent>__<ver>/ セグメントの名前になります。

スクリプトのプレフィックスの解決

<SKILL_DIR> = このスキル自体のディレクトリ（この SKILL.md があるフォルダー）の絶対パスです。コンテキスト内のスキルパスから解決し、以下に代入してください。ランタイムによってスキルのインストール先（~/.claude/skills/、~/.vibe/skills/、プラグインキャッシュ、プロジェクトの .claude/skills/ など）は異なるため、このブロックは実行時に既知のインストール先も確認し、このスキルのスクリプトが実際に存在する最初の場所を使用します。エクスポート済みの SKILL_ROOT が優先されます。

_skill=agentforce-d360-analyze
for _c in "${SKILL_ROOT:-}" "<SKILL_DIR>" \
          "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/$_skill}" \
          "${VIBES_SKILLS_DIR:+$VIBES_SKILLS_DIR/$_skill}" \
          "$HOME/.claude/skills/$_skill" "$PWD/.claude/skills/$_skill" \
          "${PLUGIN_ROOT:-$HOME/.vibe/skills}/$_skill"; do
  [ -n "$_c" ] || continue
  # Some stagers (ADK eval) nest the bundled files under <skill>/artifacts/.
  for _r in "$_c" "$_c/artifacts"; do
    [ -f "$_r/scripts/fetch_dc.py" ] && { SKILL_ROOT="$_r"; break 2; }
  done
done
[ -f "${SKILL_ROOT:-}/scripts/fetch_dc.py" ] || { echo "$_skill: scripts not found — set SKILL_ROOT to this skill's directory" >&2; exit 1; }
prefix="$SKILL_ROOT/scripts"

このドキュメント内で以降に呼び出す際は、"$prefix/..." を使用します。

セッションの検出（まだ ID がない場合）

ユーザーがセッション ID を持っていない場合は、discover_sessions.py を STDM セッション DMO に対して実行します。番号付きの選択肢が表示されるので、ユーザーに選んでもらい、選択された UUID を使って続行します。

python3 "$prefix/discover_sessions.py" [--org <alias>] [filters...]

--org は省略可能です。「自分の組織」「私たちの組織」、または別名を指定しない場合は、sf CLI のデフォルトのターゲット組織を意味します。--org を省略すると、スクリプトは sf config get target-org を使用します。ユーザーが別名を指定した場合にのみ、--org <alias> を渡します。デフォルトが設定されていない場合、スクリプトは「no --org given and no default target org set」で終了します。sf config set target-org <alias> のヒントを伝え、別名を尋ねます。

フィルター（すべて省略可能）：--since <expr>（デフォルトは過去 24 時間。「last 2 hours」、「today」、ISO 日付を受け付けます）、--agent <api-name>、--channel <Messaging|Builder|Voice>、--outcome <USER_ENDED|ESCALATED|TRANSFERRED|TIMEOUT|NOT_SET>、--grep <substring>（会話テキスト）、--tz <IANA>、--limit <N>（デフォルトは 20）。

出力：#、UUID、Start (UTC)、Agent、Channel、Duration、Outcome を含む Markdown テーブルです。ユーザーが番号で返信したら、その UUID を使って続行します。

パイプライン — 3 つのステージ

fetch_dc.py     →  24 dc.<name>.json + dc._session_manifest.json     (DC Query REST waterfall, 5 waves)
assemble_dc.py  →  dc._session_tree.json                             (pure in-memory hierarchical join)
render_dc.py    →  dc._session_summary.md                            (human summary, multi-section)

各ステージは個別に実行できます。fetch_dc.py --session <sid> [--org <alias>] は、デフォルトですべてのステージを順に実行します。

実行方法

python3 "$prefix/fetch_dc.py" --session <session-id-or-messaging-id> [--org <alias>]

ここでも --org は省略可能です。指定がない場合（ユーザーが「自分の組織」と言った場合、または別名を指定しなかった場合）は、CLI のデフォルトのターゲット組織が使用されます。デフォルトが設定されていない場合、fetch_dc.py は理由 no_org とともに DC_ACCESS_DENIED を報告します（ヘッドレス実行では終了コード 10）。別名を尋ねてから、--org <alias> を指定して再実行します。

フラグ：--verbose は DMO ごとの行数を表示します。--no-assemble／--no-render を指定すると、途中で停止します。すべてのエントリースクリプト（fetch_dc.py、assemble_dc.py、render_dc.py、resolve_session.py、discover_sessions.py）は、デフォルトの ~/.vibe/{data,cache}/agentforce-d360-analyze/ ルートを上書きするために --data-dir <path> と --cache-dir <path> を受け付けます。ホストランタイムで異なる配布レイアウトの場所にアーティファクトが必要な場合は、これらを渡します。

出力アーティファクト

すべてのファイルは ~/.vibe/data/agentforce-d360-analyze/<org_id15>/<agent>__<ver>/<session_id>/（デフォルト。--data-dir <path> で上書き可能）に保存されます。

dc.sessions.json              dc.steps.json                dc.gateway_requests.json
dc.interactions.json          dc.messages.json             dc.gateway_responses.json
dc.participants.json          dc.generations.json          dc.gateway_request_llm.json
dc.content_quality.json       dc.content_category.json     dc.gateway_request_metadata.json
dc.tags.json                  dc.tag_definitions.json      dc.gateway_request_tags.json
dc.tag_associations.json      dc.tag_definition_associations.json
dc.feedback.json              dc.feedback_details.json     dc.gateway_records.json
dc.moments.json               dc.moment_interactions.json
dc.telemetry_spans.json       dc.app_generation.json

dc._session_manifest.json     (per-DMO row counts + empties)
dc._session_tree.json         (hierarchical join — session → interactions → steps → messages → generations → gateway)
dc._session_summary.md        (rendered human summary)

結果が 0 行のクエリは、マニフェストに status: empty として記録され、ファイルは書き込まれません。assemble_dc はファイルが欠けていても処理できます。読み取り順の詳細は references/artifacts.md を参照してください。

DC のみでは見えない範囲 — 根本原因を特定する前にお読みください

DC だけで分かるのは何が起きたか、つまり実行されたステップ、発生した生成、記録されたゲートウェイリクエストです。一方、起きる可能性があったのに起きなかったことは分かりません。

• あるターンで分類器の対象となるトピックはどれだったか（これは DC ではなく、ランタイムプランナーのテレメトリーに記録されます）。
• あるトピックに対してどのアクションが宣言されていたか、また、ルール式を通過して実際に LLM に提示されたのはどれか。
• LLM が別のトピック／アクションではなく、特定のものを選んだ理由（完全なプロンプトと応答テキストは、プランナーのランタイムテレメトリーにのみ記録されます）。

ユーザーの質問が「特定のトピックやアクションが使われた、または使われなかった理由」に関するものであれば、DC のみではほとんどの場合、十分な情報が得られません。ユーザーに次のように伝えてください：「利用可否に関する質問には、そのターンのランタイムプランナートレースが必要です。これはこのスキルの Data Cloud の対象範囲外です。プランナーが記録した判断を反映するプラットフォームテレメトリーを確認してください。」ランタイムのみの証拠から根本原因をでっち上げないでください。

DC が得意なこと

• 何が実行されたか — すべてのステップ、すべての LLM 呼び出し、すべてのゲートウェイリクエストとレスポンスを、タイムスタンプと所要時間とともに順番に表示します。「セッションの流れを説明して」といった依頼に適しています。
• ユーザーが見た内容 — ユーザーとエージェントの完全なメッセージトランスクリプトを順番に表示します。
• LLM が生成した内容 — 生成内容、トークン数、信頼スコア（content_quality と content_category による有害性、指示への準拠度、コンテンツカテゴリの内訳）。
• ツール呼び出し — アクション呼び出し、入力、出力、エラー（gateway_request_metadata と gateway_records に基づきます）。
• フィードバックとフラグ — ユーザーフィードバック、エスカレーションマーカー、セッション終了タイプ。
• 監査の整合性 — GatewayRequest と GatewayResponse の 1 対 1 の不変条件をチェックし、不整合があれば counts.audit_chain_1to1_ok にフラグを記録します。

前提条件

ツール	必須
sf CLI（対象の org に対して認証済み）	はい — sf org login web --alias <alias> を実行します。また、CLI が sf org auth show-access-token を提供している必要があります（起動時の事前チェックで確認されます）
対象の org で Data Cloud が有効であること	はい — セッションの STDM + GenAI DMO がマテリアライズされている必要があります
Python 3.10+	はい — パイプラインスクリプトに必要です

典型的なプロンプト — 対応する処理

ユーザーの発言	スキルの処理
「my-org のセッション <uuid> をトレースして」	fetch_dc.py --session <uuid> --org my-org → 組み立て → レンダリング
「0Mw… で何が起きたか要約して」	0Mw… を UUID に解決し、DC パイプライン全体を実行
「my-org の Messaging で今日エスカレーションされたセッションを探して」	discover_sessions.py --since today --outcome ESCALATED --channel Messaging を実行し、選択肢を表示して、ユーザーが選択した後に DC パイプラインを実行
「このセッションの流れを説明して」	トレースと同じ処理 — レンダリングされた要約を上から順に読みます

ユーザーに返される内容

パイプラインの完了後、レンダリングされた dc._session_summary.md には次の最上位セクションが含まれます。

1. セッションの識別情報 — UUID、開始／終了時刻、所要時間、エージェント、チャネル、終了タイプ、参加者数
2. セッションの初期化 — チャネルモード + 初期化変数（identity.mode、identity.bootstrap_variables）
3. ID 参照 — 階層トレース内で省略されたすべての ID の完全な UUID
4. トランスクリプト — TURN のやり取りごとの USER ↔ AGENT の会話
5. 完全な階層トレース — Interaction → Step → Generation → GatewayRequest。「+開始 + 所要時間 = +終了」の計算式を含みます
6. ターンごとの要約 — インタラクションごとに 1 行
7. プランナーの LLM 呼び出し（完全なプロンプト + レスポンス） — --show-prompts で有効化できます。デフォルトでは非表示です
8. ビジュアル分析 — ガントチャート + LLM 呼び出しのオーバーレイ
9. セッション件数 — マニフェストの件数をまとめたエンジニア向けテーブル
10. 空データの診断 — rows == 0 で、_unavailable_reason が設定された DMO ごとに 1 行
11. カタログ（セッションでフィルタリング済み） — セッション内で確認されたエージェントに絞り込んだ TagDefinitions / TagDefinitionAssociations / Tags

詳細な調査には dc._session_tree.json を開いてください。これは要約のレンダリング元となった唯一の信頼できる情報源です。パイプラインの仕様全体については references/dc_pipeline_contract.md を、DMO ごとのフィールド参照については references/dc_dmo_fields.md を参照してください。

注意事項

• gateway_requests_dropped_by_stdm — DC が gateway_requests の行数を 0 件と報告している一方、ランタイムテレメトリでは LLM 呼び出しが実行されたことが示される場合、このスキルでは「STDM エクスポーターによる書き込みの取りこぼし」と「ソースでログ記録が実際に無効化されていた状態」を確実に区別できません。セッションは planner_ran_no_gateway_logs として報告されます。オペレーターはプラットフォームのテレメトリを確認して原因を特定できます。references/dc_pipeline_contract.md §2.8 を参照してください。
• レイテンシ — Generation と GatewayRequest には単一の書き込み時刻が記録され、開始／終了時刻のペアはありません。レンダラーはそれらの間の「レイテンシ」を計算しません。その時間差は DC のシリアライズ順を示すもので、LLM 呼び出しにかかった時間を示すものではありません。
• Data Cloud のマテリアライズ遅延 — STDM の反映が追いついていない場合、新しいセッションでは interactions_not_materialized_yet と表示されることがあります。1、2 分待ってから再実行してください。