Back to Details

investigating-agentforce-d360

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

investigating-agentforce-d360 — Data Cloud 360° session view

investigating-agentforce-d360 — Data Cloud 360°会话视图

Hierarchical session reconstruction from Data Cloud STDM + GenAI DMOs for one Agentforce session. Three stages — fetch → assemble → render. Typical wall-clock: ~10–30s for a ~15-turn session.
The pipeline is DC-only: it reads runtime audit rows that Data Cloud has materialized. It is not a runtime-availability tool — see "DC-only blind spot" below for what this skill cannot answer.
基于Data Cloud STDM + GenAI DMO的单个Agentforce会话分层重构。分为三个阶段——获取→组装→渲染。对于约15轮的会话，典型耗时约10–30秒。
该流水线仅基于DC：它读取Data Cloud已物化的运行时审计记录。它不是运行时可用性工具——以下是本技能无法回答的内容，详见下文“仅DC的盲区”。

If the user hasn't given enough to proceed

若用户未提供足够信息以继续

When invoked with no session id AND no discovery criteria, print this block verbatim — do not paraphrase, do not pre-run any script. Trigger condition: the input is empty OR contains no session-id shape (neither a UUID nor a 
0Mw…
messaging id) AND no discovery expression (no time phrase / 
--agent
/ 
--channel
/ 
--outcome
/ 
--grep
/ verbs like "find" / "list").
Which session should I pull from Data Cloud, and in which org?
I need:
  • Session id — either an Agent Session UUID (
    019db7f6-…
    ) or a MessagingSession id (
    0Mw…
    , 15/18 chars).
    • No session id? — Tell me what you remember and I'll find it: how recent (e.g. "last 2 hours", "today", a date), which agent, which channel (Messaging / Builder / Voice), how it ended (escalated, user ended, transferred, timed out), or a phrase from the conversation. I'll show matching sessions as a numbered list — you pick one, I pull it.
  • Org alias — for 
    sf
    CLI auth (the alias you configured with 
    sf org login
    ).
Artifacts land in 
~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<session_id>/
(override per-script with 
--data-dir <path>
).
当调用时既无会话ID也无发现条件，逐字打印以下内容——请勿改写，请勿预运行任何脚本。触发条件：输入为空，或不包含会话ID格式（既非UUID也非
0Mw…
格式的消息ID）且无发现表达式（无时间短语/
--agent
/
--channel
/
--outcome
/
--grep
/诸如“查找”/“列出”之类的动词）。
我应该从Data Cloud中拉取哪个会话，以及哪个组织？
我需要：
  • 会话ID —— 可以是Agent会话UUID（
    019db7f6-…
    ）或MessagingSession ID（
    0Mw…
    ，15/18个字符）。
    • 没有会话ID？ —— 告诉我你记得的信息，我来查找：会话时间（例如“过去2小时”、“今天”、某个日期）、涉及哪个代理、哪个渠道（Messaging / Builder / Voice）、会话如何结束（升级、用户结束、转接、超时），或对话中的某个短语。我会将匹配的会话以编号列表展示——你选择一个，我来拉取。
  • 组织别名 —— 用于
    sf
    CLI认证（你通过
    sf org login
    配置的别名）。
生成的产物会保存在
~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<session_id>/
（可通过脚本参数
--data-dir <path>
覆盖默认路径）。

Session id forms — UUID or MessagingSession id

会话ID格式 — UUID或MessagingSession ID

Both forms are accepted on 
--session
:
FormExampleResolution
Agent Session UUID
019dface-0000-7000-8000-000000000002
Pass-through
MessagingSession id (
0Mw
prefix)
0MwTESTMSG12345AAA
Resolved via 
resolve_session.py
— live DC lookup on first fetch, disk-first thereafter
Multi-match is real. One MessagingSession id can map to multiple Agent Session UUIDs. On multi-match the resolver prints every candidate and exits non-zero; the user re-invokes with a specific UUID.
Artifacts always land under 
~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<session_id>/
(default; overridable per-script with 
--data-dir <path>
) — the messaging id is a lookup key only, never a directory name. The dominant agent (first in 
sorted(agents_observed)
) names the 
<agent>__<ver>/
segment.
--session
参数接受两种格式：
格式示例解析方式
Agent会话UUID
019dface-0000-7000-8000-000000000002
直接传递
MessagingSession ID（
0Mw
前缀）
0MwTESTMSG12345AAA
通过
resolve_session.py
解析——首次拉取时实时查询DC，后续优先从磁盘缓存读取
存在多匹配情况。一个MessagingSession ID可能对应多个Agent会话UUID。出现多匹配时，解析器会打印所有候选并以非零状态退出；用户需使用特定UUID重新调用。
产物始终保存在
~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<session_id>/
（默认路径；可通过脚本参数
--data-dir <path>
覆盖）——消息ID仅作为查找键，绝不会作为目录名。主导代理（
sorted(agents_observed)
中的第一个）命名
<agent>__<ver>/
目录段。

Resolving the script prefix

解析脚本前缀

The default install puts the skill under the runtime's plugin root. If the skill was cloned somewhere else (e.g. directly from the 
forcedotcom/sf-skills
repo into a custom path), set 
PLUGIN_ROOT
to point at the runtime's skills directory.
bash
prefix="${SKILL_ROOT:-${PLUGIN_ROOT:-$HOME/.vibe/skills}/investigating-agentforce-d360}/scripts"
Every subsequent invocation in this doc uses 
"$prefix/..."
.
默认安装会将技能放在运行时的插件根目录下。如果技能被克隆到其他位置（例如直接从
forcedotcom/sf-skills
仓库克隆到自定义路径），请设置
PLUGIN_ROOT
指向运行时的技能目录。
bash
prefix="${SKILL_ROOT:-${PLUGIN_ROOT:-$HOME/.vibe/skills}/investigating-agentforce-d360}/scripts"
本文档中后续所有调用均使用
"$prefix/..."
。

Session discovery (no id yet)

会话发现（尚无ID时）

When the user doesn't have a session id, run 
discover_sessions.py
against the STDM session DMO. Prints a numbered picker; user picks one; proceed with the chosen UUID.
bash
python3 "$prefix/discover_sessions.py" --org <alias> [filters...]
Filters (all optional except 
--org
): 
--since <expr>
(default last 24h; accepts "last 2 hours", "today", ISO dates), 
--agent <api-name>
, 
--channel <Messaging|Builder|Voice>
, 
--outcome <USER_ENDED|ESCALATED|TRANSFERRED|TIMEOUT|NOT_SET>
, 
--grep <substring>
(conversation text), 
--tz <IANA>
, 
--limit <N>
(default 20).
Output: markdown table with 
#
, 
UUID
, 
Start (UTC)
, 
Agent
, 
Channel
, 
Duration
, 
Outcome
. User replies with a number; proceed with that UUID.
当用户没有会话ID时，针对STDM会话DMO运行
discover_sessions.py
。打印编号选择器；用户选择一个；使用选中的UUID继续操作。
bash
python3 "$prefix/discover_sessions.py" --org <alias> [filters...]
筛选器（除
--org
外均为可选）：
--since <expr>
（默认过去24小时；接受“过去2小时”、“今天”、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继续操作。

Pipeline — three stages

流水线 — 三个阶段

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)
Each stage is independently runnable. 
fetch_dc.py --session <sid> --org <alias>
chains all three by default.
fetch_dc.py     →  24个dc.<name>.json + dc._session_manifest.json     (DC Query REST API请求瀑布流，5轮请求)
assemble_dc.py  →  dc._session_tree.json                             (纯内存分层关联)
render_dc.py    →  dc._session_summary.md                            (人工可读摘要，多章节)
每个阶段均可独立运行。默认情况下，
fetch_dc.py --session <sid> --org <alias>
会链式执行这三个阶段。

Invocation

调用方式

bash
python3 "$prefix/fetch_dc.py" --session <session-id-or-messaging-id> --org <alias>
Flags: 
--verbose
for per-DMO row counts; 
--no-assemble
/ 
--no-render
to stop early. All entry scripts (
fetch_dc.py
, 
assemble_dc.py
, 
render_dc.py
, 
resolve_session.py
, 
discover_sessions.py
) accept 
--data-dir <path>
and 
--cache-dir <path>
to override the default 
~/.vibe/{data,cache}/investigating-agentforce-d360/
roots — pass these when the host runtime needs artifacts under a different distribution layout.
bash
python3 "$prefix/fetch_dc.py" --session <会话ID或消息ID> --org <别名>
参数：
--verbose
用于显示每个DMO的记录数；
--no-assemble
/
--no-render
用于提前终止流程。所有入口脚本（
fetch_dc.py
、
assemble_dc.py
、
render_dc.py
、
resolve_session.py
、
discover_sessions.py
）均接受
--data-dir <path>
和
--cache-dir <path>
参数，用于覆盖默认的
~/.vibe/{data,cache}/investigating-agentforce-d360/
根目录——当宿主运行时需要将产物放在不同的分发路径下时，可传递这些参数。

Output artifacts

输出产物

Everything lands under 
~/.vibe/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<session_id>/
(default; override with 
--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)
Zero-row queries are recorded in the manifest with 
status: empty
; no file is written. 
assemble_dc
tolerates missing files. See 
references/artifacts.md
for the full read order.
所有产物均保存在
~/.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     (每个DMO的记录数 + 空记录标识)
dc._session_tree.json         (分层关联 — 会话 → 交互 → 步骤 → 消息 → 生成内容 → 网关请求)
dc._session_summary.md        (渲染后的人工可读摘要)
零记录查询会在清单中标记为
status: empty
；不会生成对应文件。
assemble_dc
可以容忍缺失文件。完整的读取顺序详见
references/artifacts.md
。

The DC-only blind spot — read before committing to a root cause

仅DC的盲区 — 确定根本原因前请阅读

DC alone answers what happened — steps that ran, generations that fired, gateway requests that were logged. It does NOT answer what could have happened but didn't:
  • Which topics were eligible for the classifier on a given turn (this lives in runtime planner telemetry, not DC).
  • Which actions were declared on a topic vs. which survived rule expressions and were actually offered to the LLM.
  • Why the LLM picked one topic/action over another (the full prompt + response text only lives in the planner runtime telemetry).
If the user's question is about why a particular topic or action was or wasn't used, DC-only is almost never sufficient. Tell the user: "Availability questions need the runtime planner trace for that turn — which is outside this skill's Data Cloud surface. Check the platform telemetry that mirrors the planner's logged decisions." Don't fabricate a root cause from runtime-only evidence.
仅靠DC只能回答发生了什么——运行的步骤、触发的生成操作、记录的网关请求。它无法回答本可能发生但实际未发生的情况：
  • 在某一轮对话中，分类器符合条件的主题有哪些（该信息存在于运行时规划器遥测数据中，而非DC）。
  • 某个主题上声明了哪些动作，与通过规则表达式筛选后实际提供给LLM的动作有哪些差异。
  • 为什么LLM选择某个主题/动作而非其他（完整的提示词+响应文本仅存在于规划器运行时遥测数据中）。
如果用户的问题是关于为什么某个特定主题或动作被使用或未被使用，仅靠DC几乎永远不够。请告知用户：“可用性问题需要对应轮次的运行时规划器追踪数据——这超出了本技能的Data Cloud覆盖范围。请查看镜像规划器日志决策的平台遥测数据。”请勿仅根据运行时证据编造根本原因。

What DC IS good at

DC擅长的场景

  • What ran — every step, every LLM call, every gateway request + response, in order, with timestamps and durations. Good for "walk me through the session".
  • What the user saw — full message transcript (user + agent), ordered.
  • What the LLM produced — generations, token counts, trust scores (toxicity, instruction adherence, content-category breakdown from 
    content_quality
    + 
    content_category
    ).
  • Tool invocations — action calls, inputs, outputs, errors (from 
    gateway_request_metadata
    + 
    gateway_records
    ).
  • Feedback + flags — user feedback, escalation markers, session-end type.
  • Audit integrity — the 1:1 invariant between GatewayRequest and GatewayResponse is checked; drift is flagged in 
    counts.audit_chain_1to1_ok
    .
  • 运行了什么——每个步骤、每个LLM调用、每个网关请求+响应，按顺序排列，包含时间戳和时长。适用于“带我梳理整个会话”的需求。
  • 用户看到了什么——完整的消息对话记录（用户+代理），按顺序排列。
  • LLM生成了什么——生成内容、令牌数、信任分数（毒性、指令依从性、来自
    content_quality
    +
    content_category
    的内容类别细分）。
  • 工具调用——动作调用、输入、输出、错误（来自
    gateway_request_metadata
    +
    gateway_records
    ）。
  • 反馈与标记——用户反馈、升级标记、会话结束类型。
  • 审计完整性——检查GatewayRequest与GatewayResponse之间1:1的一致性；若存在偏差，会在
    counts.audit_chain_1to1_ok
    中标记。

Prerequisites

前置条件

ToolRequired
sf
CLI (authenticated against the target org)		yes — 
sf org login web --alias <alias>
Data Cloud enabled on the target orgyes — the STDM + GenAI DMOs must have materialized for the session
Python 3.10+yes — pipeline scripts
工具是否必需
sf
CLI（已针对目标组织完成认证）		是 —— 
sf org login web --alias <alias>
目标组织已启用Data Cloud是 —— 会话对应的STDM + GenAI DMO必须已完成物化
Python 3.10+是 —— 流水线脚本依赖

Typical prompts — what they map to

典型提示语 — 对应操作

User saysSkill does
"Trace session 
<uuid>
in my-org"
fetch_dc.py --session <uuid> --org my-org
→ assemble → render
"Summarize what happened in 
0Mw…
"		Resolve 
0Mw…
→ UUID, then full DC pipeline
"Find escalated sessions today in my-org on Messaging"Run 
discover_sessions.py --since today --outcome ESCALATED --channel Messaging
, print picker, user picks, then DC pipeline
"Walk me through this session"Same as trace — read the rendered summary top to bottom
用户表述技能执行操作
“在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流水线
“带我梳理这个会话”与追踪操作相同——从头到尾读取渲染后的摘要

What comes back to the user

返回给用户的内容

After the pipeline completes, the rendered 
dc._session_summary.md
carries these top-level sections:
  1. Session identity — UUID, start/end, duration, agent, channel, end type, participant counts
  2. Session bootstrap — channel mode + bootstrap variables (
    identity.mode
    , 
    identity.bootstrap_variables
    )
  3. ID reference — full UUIDs for everything truncated in the hierarchical trace
  4. Transcript — USER ↔ AGENT narrative per TURN interaction
  5. Complete hierarchical trace — Interaction → Step → Generation → GatewayRequest, with 
    +start + duration = +end
    math
  6. Per-turn summary — one row per interaction
  7. Planner LLM calls (full prompts + responses) — opt-in via 
    --show-prompts
    ; suppressed by default
  8. Visual analysis — gantt + LLM-call overlay
  9. Session counts — engineer-facing table of manifest counts
  10. Empties diagnostics — one row per DMO with 
    rows == 0
    and a populated 
    _unavailable_reason
  11. Catalog (session-filtered) — TagDefinitions / TagDefinitionAssociations / Tags filtered to agents observed in the session
For deep-dive, open 
dc._session_tree.json
— the single source of truth the summary was rendered from. See 
references/dc_pipeline_contract.md
for the full pipeline contract and 
references/dc_dmo_fields.md
for per-DMO field reference.
流水线完成后，渲染后的
dc._session_summary.md
包含以下顶级章节：
  1. 会话标识——UUID、开始/结束时间、时长、代理、渠道、结束类型、参与者数量
  2. 会话引导信息——渠道模式+引导变量（
    identity.mode
    、
    identity.bootstrap_variables
    ）
  3. ID参考——分层追踪中所有截断内容的完整UUID
  4. 对话记录——每轮交互的USER ↔ AGENT叙事内容
  5. 完整分层追踪——Interaction → Step → Generation → GatewayRequest，附带
    +开始时间 + 时长 = +结束时间
    计算
  6. 每轮会话摘要——每轮交互对应一行内容
  7. 规划器LLM调用（完整提示词+响应）——需通过
    --show-prompts
    参数启用；默认隐藏
  8. 可视化分析——甘特图+LLM调用叠加层
  9. 会话统计——面向工程师的清单统计表格
  10. 空记录诊断——每个DMO对应一行，若
    rows == 0
    则显示填充的
    _unavailable_reason
  11. 目录（会话筛选后）——筛选出会话中涉及的代理对应的TagDefinitions / TagDefinitionAssociations / Tags
如需深入分析，请打开
dc._session_tree.json
——这是生成摘要的唯一可信数据源。完整的流水线契约详见
references/dc_pipeline_contract.md
，每个DMO的字段参考详见
references/dc_dmo_fields.md
。

Caveats

注意事项

  • gateway_requests_dropped_by_stdm
     — when DC reports zero 
    gateway_requests
    rows but runtime telemetry would show LLM calls did fire, this skill cannot definitively distinguish "STDM exporter dropped writes" from "logging genuinely disabled at the source". The session is reported as 
    planner_ran_no_gateway_logs
    ; the operator can check platform telemetry to disambiguate. See 
    references/dc_pipeline_contract.md
    §2.8.
  • Latency — Generation and GatewayRequest carry single-write timestamps, not start/end pairs. The renderer does not compute "latencies" between them — that delta reflects DC's serialization order, not how long the LLM call took.
  • Data Cloud materialization lag — fresh sessions may show 
    interactions_not_materialized_yet
    if STDM hasn't caught up. Re-run after a minute or two.
  • 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分钟后重新运行。