mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-05 06:41:42 +08:00
20ae436442
Data Cloud 360° view of a single Agentforce session — DC-only, zero
Splunk dependency. Pulls 24 STDM + GenAI DMOs via the Data Cloud Query
REST API, assembles a hierarchical session tree (Interaction → Step →
Generation → GatewayRequest), and renders a human-readable markdown
summary with transcript + per-turn topic/action invocations + LLM
generations + tool calls + audit chain.
Migrated as a standalone Apache-2.0 skill from an internal hub plugin —
self-contained, no sibling-skill or plugin dependencies.
What this skill answers:
- "Trace session <uuid>" / "Summarize what happened in <0Mw…>"
- "Find escalated sessions today on Messaging in <org>"
- Session discovery by time / agent / channel / outcome / conversation
text when the user has no session id
What it does NOT answer (use a different surface):
- Design-time architecture — use investigating-agentforce-architecture
- Runtime planner availability — DC alone can't tell you which
topic/action was eligible for the classifier on a given turn
Skill layout:
- 8 Python pipeline modules (fetch_dc, assemble_dc, render_dc,
discover_sessions, resolve_session, dc, storage, config)
- 4 _shared helpers (paths, fs_guard, sql, __init__) with skill-scoped
DATA_ROOT (~/.claude/data/investigating-agentforce-d360/)
- 26 SQL templates under assets/dc/
- 27 test files (367 tests + 18 subtests, 100% passing)
- 3 reference docs (artifacts.md, dc_dmo_fields.md,
dc_pipeline_contract.md)
- SKILL.md (sf-skills frontmatter, license: Apache-2.0,
metadata.version: "1.0")
- README.md (external-facing quick-start)
- tools/grant_allowlist.py (idempotent first-run permission grant)
- tools/archive_data_dir.sh (opt-in stop-hook tarballer)
Quality gates:
- pytest scripts/tests/: 367 passed + 18 subtests, 0 failures
- npm run validate:skills: 62 of 62 skill(s) checked, 0 errors
- Live end-to-end runs against 3 real Salesforce sessions exercising
both the full-tree and STDM-lag gateway-direct render branches
- 4 independent code-review rounds (correctness, security, markdown,
architecture-critic) — all findings addressed
Customer-data hygiene: no live tenant ids, no internal sprint markers,
no hub/sibling-skill references. Synthetic fixtures look obviously
synthetic (`019dface-…` UUIDs, `0MwTESTMSG…` MessagingSession ids,
`00DTESTORG…` org ids, `MyAgent` placeholder agent name).
Sibling skill: investigating-agentforce-architecture (PR #278) — same
migration pattern, design-time metadata; complementary scope.
51 lines
2.8 KiB
Markdown
51 lines
2.8 KiB
Markdown
# Artifacts reference
|
|
|
|
Every successful trace lands artifacts under
|
|
`~/.claude/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<sid>/`.
|
|
Re-running the same `(org, sid)` overwrites in place. Listed below in
|
|
the order they're produced.
|
|
|
|
```
|
|
~/.claude/data/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<sid>/
|
|
├── dc._session_manifest.json ← per-query counts + session_shape + empties
|
|
├── dc._session_tree.json ← hierarchical join (primary artifact)
|
|
├── dc._session_summary.md ← human-readable summary, up to 11 sections (varies with session_shape + identity bootstrap + --show-prompts opt-in)
|
|
├── dc.sessions.json ← 1 row (STDM session)
|
|
├── dc.interactions.json ← N rows (TURN + SESSION_END)
|
|
├── dc.messages.json ← USER + AGENT messages
|
|
├── dc.steps.json ← LLM_STEP / ACTION_STEP / TOPIC_STEP / TRUST_GUARDRAILS_STEP / SESSION_END
|
|
├── dc.participants.json ← USER + AGENT participants
|
|
├── dc.generations.json ← LLM generations
|
|
├── dc.gateway_requests.json ← gateway-logged LLM calls
|
|
├── dc.gateway_responses.json ← 1:1 with gateway_requests
|
|
├── dc.gateway_request_tags.json ← tag rows (bot_id, agent_version_api_name, etc.)
|
|
├── dc.gateway_request_metadata.json ← per-call metadata
|
|
├── dc.content_quality.json ← Trust Layer quality scores
|
|
├── dc.content_category.json ← toxicity + other category rows
|
|
├── dc.feedback.json ← user thumbs-up/down (often empty)
|
|
├── dc.feedback_details.json ← feedback text (often empty)
|
|
├── dc.moments.json ← optional Agent Optimization rollup (often empty)
|
|
├── dc.moment_interactions.json ← moment→interaction junction (often empty)
|
|
├── dc.tag_*.json ← org-wide agent tag catalog (often empty)
|
|
├── dc.telemetry_spans.json ← usually empty (Agent Platform Tracing off)
|
|
├── dc.app_generation.json ← reserved, always empty today
|
|
├── dc.gateway_records.json ← grounded attachments (rare)
|
|
├── dc.gateway_request_llm.json ← writer inactive on observed orgs
|
|
└── dc.tag_associations.json ← agent↔tag links (often empty)
|
|
```
|
|
|
|
## Read order
|
|
|
|
1. **`dc._session_summary.md`** — human-readable, top-to-bottom answers
|
|
"what happened in this session?"
|
|
2. **`dc._session_tree.json`** — single source of truth, the
|
|
hierarchical join the summary was rendered from. Open this when the
|
|
summary is missing a detail you need.
|
|
3. **`dc._session_manifest.json`** — per-DMO row counts, classified
|
|
`session_shape`, and empty-by-design reasons for any DMO that
|
|
returned zero rows. Open this when something looks missing in the
|
|
tree.
|
|
4. **`dc.<name>.json`** — raw per-DMO rows. Only needed when the
|
|
manifest reports an unexpected count or the assembler logs a parse
|
|
warning.
|