investigating-agentforce-d360

investigating-agentforce-d360 — 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／「find」や「list」のような動詞）も含まれていない場合です。

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

次の情報が必要です。

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

アーティファクトは ~/.vibe/data/investigating-agentforce-d360/<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 で解決します。初回取得時は DC をライブ検索し、以降はディスクを優先します

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

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

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

デフォルトのインストールでは、ランタイムのプラグインルートの下にスキルが配置されます。 スキルを別の場所にクローンした場合（例：forcedotcom/sf-skills リポジトリから カスタムパスへ直接クローンした場合）は、PLUGIN_ROOT をランタイムのスキル ディレクトリに設定してください。

prefix="${SKILL_ROOT:-${PLUGIN_ROOT:-$HOME/.vibe/skills}/investigating-agentforce-d360}/scripts"

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

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

ユーザーがセッション ID を持っていない場合は、STDM セッション DMO に対して discover_sessions.py を実行します。番号付きの選択リストが表示されます。ユーザーが 1 つ選んだら、その UUID を使用して続行します。

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

フィルター（--org 以外はすべて省略可能）：--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> が 3 つすべてを連続して実行します。

呼び出し

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

フラグ：DMO ごとの行数を表示する --verbose、早い段階で停止する --no-assemble ／ --no-render。すべてのエントリースクリプト（fetch_dc.py、assemble_dc.py、render_dc.py、resolve_session.py、discover_sessions.py）では、デフォルトの ~/.vibe/{data,cache}/investigating-agentforce-d360/ のルートを上書きするために --data-dir <path> と --cache-dir <path> を指定できます。ホストランタイムで別の配布レイアウト配下に成果物を置く必要がある場合は、これらを指定してください。

出力成果物

すべての成果物は ~/.vibe/data/investigating-agentforce-d360/<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（対象組織に対して認証済み）	はい — sf org login web --alias <alias>
対象組織で 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 と、+start + duration = +end の計算
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 行数がゼロでも、ランタイムテレメトリでは 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 分後に再実行してください。