Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-d360-analyze

agentforce-d360-analyze

Verified

Data Cloud 360° view of a single Agentforce session. TRIGGER when user asks to trace, inspect, summarize, or describe a specific Agentforce session by session id (Agent Session UUID `019d…` or MessagingSession id `0Mw…`). Also triggers on session discovery — find/list/search sessions by time, agent, channel, outcome, or conversation text — when the user has no session id yet. DO NOT TRIGGER for design-time architecture questions (use agentforce-architecture-analyze instead) or for runtime perf/latency/SLO questions that require platform telemetry beyond Data Cloud.

FileKindSize
README.mdmarkdown6.2 KB
SKILL.mdskill md13.2 KB
assets/dc/app_generation.sqlother1.9 KB
assets/dc/content_category.sqlother1.5 KB
assets/dc/content_quality.sqlother1.3 KB
assets/dc/discover_sessions.sqlother2.3 KB
assets/dc/feedback.sqlother1.5 KB
assets/dc/feedback_details.sqlother1.3 KB
assets/dc/gateway_records.sqlother1.6 KB
assets/dc/gateway_request_llm.sqlother1.6 KB
assets/dc/gateway_request_metadata.sqlother1.5 KB
assets/dc/gateway_request_tags.sqlother1.4 KB
assets/dc/gateway_requests.sqlother3.4 KB
assets/dc/gateway_responses.sqlother1.7 KB
assets/dc/generations.sqlother1.9 KB
assets/dc/interactions.sqlother2.0 KB
assets/dc/messages.sqlother2.1 KB
assets/dc/messaging_session.sqlother1.7 KB
assets/dc/moment_interactions.sqlother1.4 KB
assets/dc/moments.sqlother1.5 KB
assets/dc/participants.sqlother1.8 KB
assets/dc/sessions.sqlother3.0 KB
assets/dc/steps.sqlother2.6 KB
assets/dc/tag_associations.sqlother1.7 KB
assets/dc/tag_definition_associations.sqlother1.4 KB
assets/dc/tag_definitions.sqlother1.8 KB
assets/dc/tags.sqlother1.3 KB
assets/dc/telemetry_spans.sqlother2.1 KB
references/artifacts.mdmarkdown2.7 KB
references/dc_dmo_fields.mdmarkdown42.1 KB
references/dc_pipeline_contract.mdmarkdown26.3 KB
scripts/_shared/__init__.pyscript122 B
scripts/_shared/cli_override.pyscript3.3 KB
scripts/_shared/fs_guard.pyexecutablescript13.2 KB
scripts/_shared/paths.pyscript5.8 KB
scripts/_shared/runtime.pyscript2.0 KB
scripts/_shared/sql.pyscript548 B
scripts/assemble_dc.pyscript69.6 KB
scripts/config.pyscript1.8 KB
scripts/dc.pyscript13.8 KB
scripts/discover_sessions.pyscript21.1 KB
scripts/fetch_dc.pyscript45.1 KB
scripts/render_dc.pyscript69.7 KB
scripts/resolve_session.pyscript10.8 KB
scripts/storage.pyscript3.1 KB
scripts/tests/__init__.pyscript0 B
scripts/tests/_bootstrap.pyscript483 B
scripts/tests/fixtures/__init__.pyscript0 B
scripts/tests/fixtures/synthetic_session.pyscript14.6 KB
scripts/tests/test_assemble_dc_bootstrap_and_mode.pyscript4.2 KB
scripts/tests/test_assemble_dc_gateway_direct.pyscript8.3 KB
scripts/tests/test_assemble_dc_gateway_direct_integration.pyscript6.4 KB
scripts/tests/test_assemble_dc_helpers.pyscript10.0 KB
scripts/tests/test_assemble_dc_integration.pyscript9.3 KB
scripts/tests/test_dc_and_resolve_session.pyscript26.7 KB
scripts/tests/test_default_target_org.pyscript18.8 KB
scripts/tests/test_discover_sessions.pyscript19.0 KB
scripts/tests/test_discover_sessions_grep_ci.pyscript8.2 KB
scripts/tests/test_fetch_dc_helpers.pyscript10.6 KB
scripts/tests/test_fetch_dc_identity.pyscript22.0 KB
scripts/tests/test_fetch_dc_main.pyscript9.4 KB
scripts/tests/test_fetch_dc_waterfall.pyscript8.6 KB
scripts/tests/test_fetch_dc_waterfall_full.pyscript11.2 KB
scripts/tests/test_identity_coherence.pyscript13.8 KB
scripts/tests/test_render_dc_branches.pyscript9.9 KB
scripts/tests/test_render_dc_gateway_direct.pyscript5.1 KB
scripts/tests/test_render_dc_helpers.pyscript10.5 KB
scripts/tests/test_render_dc_integration.pyscript7.7 KB
scripts/tests/test_render_dc_planner_llm_calls.pyscript11.8 KB
scripts/tests/test_render_dc_show_prompts_gating.pyscript8.7 KB
scripts/tests/test_resolve_from_disk.pyscript4.1 KB
scripts/tests/test_resolve_session_main.pyscript5.2 KB
scripts/tests/test_runtime_override.pyscript4.2 KB
scripts/tests/test_session_shape.pyscript3.5 KB
scripts/tests/test_session_shape_dropped_by_stdm.pyscript3.5 KB
scripts/tests/test_skill_md_prefix_block.pyscript6.8 KB

scripts/tests/fixtures/synthetic_session.py

View on GitHub
"""Synthetic session fixture for d360 integration tests.

Provides:

- ``IDS``           a flat namespace of all UUIDs/keys used so tests
                    can assert against specific values.
- ``make_rows()``   returns ``{dmo_name: [row, ...]}`` for the 24 DMOs
                    `assemble_dc` reads. Self-consistent: every
                    Step.GenerationId references a Generation row, etc.
- ``make_manifest`` returns the dc._session_manifest.json shape.
- ``write_to_disk`` materializes the whole fixture under a session dir
                    so tests that drive the public ``assemble_dc.assemble``
                    can use ``tmp_path`` + DATA_ROOT redirect without
                    duplicating layout knowledge.

Shape rules:
  - Timestamps anchored on 2026-04-22T10:00:00Z; offsets in seconds.
  - All ssot__Id__c values are 18-char-stable strings (not real Salesforce
    IDs) — assemble_dc only key-equality-checks them.
  - HTML escaping applied to AttributeText__c so the trace_id fallback
    path exercises real code.
  - parameters__c on gateway_responses uses the "-escaped JSON shape
    real DC emits.
"""
from __future__ import annotations

import html
import json
from copy import deepcopy
from pathlib import Path
from typing import Any, Dict, List


# -----------------------------------------------------------------------------
# IDs — exposed flat for cross-test assertions
# -----------------------------------------------------------------------------


class _IDs:
    SID = "019dface-0000-7000-8000-000000000001"
    """Agent session UUID. Valid UUIDv7 so window decode works."""

    ORG_ID_15 = "00D000000000ABC"
    ORG_ID_18 = "00D000000000ABCDEF"
    AGENT_API = "DemoAgent"
    AGENT_VERSION = "v5"
    BOT_ID = "0Xx000000000DemoBot"

    # Interactions
    IXN_START = "ixn-start-001"
    IXN_TURN = "ixn-turn-002"
    IXN_END = "ixn-end-003"

    # Steps within the TURN
    STEP_TOPIC = "step-topic-001"
    STEP_ACTION = "step-action-002"
    STEP_GUARDRAIL = "step-guardrail-003"

    # Gateway audit chain — one declared, one timestamp-window-only
    GW_REQ_DECLARED = "gw-req-declared-001"
    GW_REQ_WINDOW = "gw-req-window-002"
    GW_RESP_DECLARED = "gw-resp-declared-001"

    # Generation chain (declared)
    GEN_DECLARED = "gen-declared-001"

    # Participants
    PART_AGENT = "part-agent-001"
    PART_USER = "part-user-002"

    # Trace + window
    TRACE_ID = "8b820e85aaaaaaaabbbbbbbbcccccccc"
    SESSION_START = "2026-04-22T10:00:00.000Z"
    SESSION_END = "2026-04-22T10:01:30.000Z"
    TURN_START = "2026-04-22T10:00:05.000Z"
    TURN_END = "2026-04-22T10:01:00.000Z"
    GW_DECLARED_TS = "2026-04-22T10:00:30.000Z"  # inside step-action window
    GW_WINDOW_TS = "2026-04-22T10:00:45.000Z"   # inside the TURN window only


IDS = _IDs


# -----------------------------------------------------------------------------
# Per-DMO row builders
# -----------------------------------------------------------------------------


def _sessions() -> List[dict]:
    return [{
        "ssot__Id__c": IDS.SID,
        "ssot__InternalOrganizationId__c": IDS.ORG_ID_18,
        "ssot__StartTimestamp__c": IDS.SESSION_START,
        "ssot__EndTimestamp__c": IDS.SESSION_END,
        "ssot__AiAgentChannelType__c": "SCRT2 - EmbeddedMessaging",
        "ssot__AiAgentSessionEndType__c": "USER_ENDED",
        "ssot__RelatedMessagingSessionId__c": "0MwTESTMSG12345AAA",
    }]


def _interactions() -> List[dict]:
    """Three interactions: SESSION_START, TURN, SESSION_END.

    `AttributeText__c` carries the real internalTraceId in HTML-escaped
    JSON form on the TURN row (matches live DC shape).
    """
    # No spaces in separators — production logger emits compact JSON, and
    # the trace_id regex (`"internalTraceId":"([a-f0-9]+)"`) requires no
    # whitespace around the colon.
    raw_attr_text = json.dumps(
        {"internalTraceId": IDS.TRACE_ID, "label": "react-loop"},
        separators=(",", ":"),
    )
    return [
        {
            "ssot__Id__c": IDS.IXN_START,
            "ssot__AiAgentSessionId__c": IDS.SID,
            "ssot__AiAgentInteractionType__c": "SESSION_START",
            "ssot__StartTimestamp__c": IDS.SESSION_START,
            "ssot__EndTimestamp__c": IDS.SESSION_START,
            "ssot__TelemetryTraceId__c": "",
            "ssot__AttributeText__c": "",
        },
        {
            "ssot__Id__c": IDS.IXN_TURN,
            "ssot__AiAgentSessionId__c": IDS.SID,
            "ssot__AiAgentInteractionType__c": "TURN",
            "ssot__StartTimestamp__c": IDS.TURN_START,
            "ssot__EndTimestamp__c": IDS.TURN_END,
            "ssot__TelemetryTraceId__c": "",
            # HTML-escaped JSON triggers the AttributeText fallback path.
            "ssot__AttributeText__c": html.escape(raw_attr_text, quote=True),
        },
        {
            "ssot__Id__c": IDS.IXN_END,
            "ssot__AiAgentSessionId__c": IDS.SID,
            "ssot__AiAgentInteractionType__c": "SESSION_END",
            "ssot__StartTimestamp__c": IDS.SESSION_END,
            "ssot__EndTimestamp__c": IDS.SESSION_END,
            "ssot__TelemetryTraceId__c": "NOT_SET",
            "ssot__AttributeText__c": "",
        },
    ]


def _steps() -> List[dict]:
    """Three steps inside the TURN. Step times nest inside the turn window
    so the timestamp-window pass binds gateway_requests by containment."""
    return [
        {
            "ssot__Id__c": IDS.STEP_TOPIC,
            "ssot__AiAgentInteractionId__c": IDS.IXN_TURN,
            "ssot__AiAgentInteractionStepType__c": "TOPIC_STEP",
            "ssot__StartTimestamp__c": "2026-04-22T10:00:10.000Z",
            "ssot__EndTimestamp__c": "2026-04-22T10:00:20.000Z",
            "ssot__GenerationId__c": "NOT_SET",
            "ssot__Name__c": "TopicSelection",
        },
        {
            "ssot__Id__c": IDS.STEP_ACTION,
            "ssot__AiAgentInteractionId__c": IDS.IXN_TURN,
            "ssot__AiAgentInteractionStepType__c": "ACTION_STEP",
            "ssot__StartTimestamp__c": "2026-04-22T10:00:25.000Z",
            "ssot__EndTimestamp__c": "2026-04-22T10:00:40.000Z",
            "ssot__GenerationId__c": IDS.GEN_DECLARED,
            "ssot__Name__c": "PrimaryAction",
        },
        {
            "ssot__Id__c": IDS.STEP_GUARDRAIL,
            "ssot__AiAgentInteractionId__c": IDS.IXN_TURN,
            "ssot__AiAgentInteractionStepType__c": "TRUST_GUARDRAILS_STEP",
            "ssot__StartTimestamp__c": "2026-04-22T10:00:55.000Z",
            "ssot__EndTimestamp__c": "2026-04-22T10:01:00.000Z",
            "ssot__GenerationId__c": "NOT_SET",
            "ssot__Name__c": "FinalGuard",
        },
    ]


def _messages() -> List[dict]:
    return [
        {
            "ssot__Id__c": "msg-001",
            "ssot__AiAgentInteractionId__c": IDS.IXN_TURN,
            "ssot__AiAgentInteractionMessageType__c": "USER",
            "ssot__ContentText__c": "How do I refund my order?",
            "ssot__StartTimestamp__c": IDS.TURN_START,
        },
        {
            "ssot__Id__c": "msg-002",
            "ssot__AiAgentInteractionId__c": IDS.IXN_TURN,
            "ssot__AiAgentInteractionMessageType__c": "AGENT",
            "ssot__ContentText__c": "I'll help you with the refund process.",
            "ssot__StartTimestamp__c": IDS.TURN_END,
        },
    ]


def _participants() -> List[dict]:
    return [
        {
            "ssot__Id__c": IDS.PART_AGENT,
            "ssot__AiAgentSessionId__c": IDS.SID,
            "ssot__AiAgentSessionParticipantRole__c": "AGENT",
            "ssot__AiAgentApiName__c": IDS.AGENT_API,
            "ssot__AiAgentVersionApiName__c": IDS.AGENT_VERSION,
        },
        {
            "ssot__Id__c": IDS.PART_USER,
            "ssot__AiAgentSessionId__c": IDS.SID,
            "ssot__AiAgentSessionParticipantRole__c": "USER",
            "ssot__AiAgentApiName__c": "",
            "ssot__AiAgentVersionApiName__c": "",
        },
    ]


def _gateway_requests() -> List[dict]:
    """Two gateway requests:

    - GW_REQ_DECLARED: chained from Step → Generation → Response → Request.
      Timestamp also falls within step-action window so either binding
      method can resolve it. Declared chain wins.

    - GW_REQ_WINDOW: NOT in the declared chain. Timestamp falls inside
      the TURN window → exercise timestamp-window fallback.
    """
    return [
        {
            "gatewayRequestId__c": IDS.GW_REQ_DECLARED,
            "sf__Id": "sf-" + IDS.GW_REQ_DECLARED,
            "sessionId__c": f'"{IDS.SID}"',
            "timestamp__c": IDS.GW_DECLARED_TS,
            "model__c": "gpt-4o",
            "provider__c": "openai",
            "promptTemplateDevName__c": "AiCopilot__ReactInitialPrompt",
            "feature__c": "plannerservice",
            "promptTokens__c": 1200,
            "completionTokens__c": 50,
            "totalTokens__c": 1250,
            "prompt__c": "Declared-bound prompt body.",
        },
        {
            "gatewayRequestId__c": IDS.GW_REQ_WINDOW,
            "sf__Id": "sf-" + IDS.GW_REQ_WINDOW,
            "sessionId__c": f'"{IDS.SID}"',
            "timestamp__c": IDS.GW_WINDOW_TS,
            "model__c": "gpt-4o-mini",
            "provider__c": "openai",
            "promptTemplateDevName__c": "AiCopilot__PromptTemplateGenerationsInvocable",
            "feature__c": "plannerservice",
            "promptTokens__c": 200,
            "completionTokens__c": 20,
            "totalTokens__c": 220,
            "prompt__c": "Window-bound prompt body.",
        },
    ]


def _gateway_responses() -> List[dict]:
    raw = '{"finish_reason":"\\"stop\\""}'
    escaped = raw.replace('"', """)
    return [{
        "generationResponseId__c": IDS.GW_RESP_DECLARED,
        "generationRequestId__c": IDS.GW_REQ_DECLARED,
        "parameters__c": escaped,
        "timestamp__c": IDS.GW_DECLARED_TS,
    }]


def _generations() -> List[dict]:
    return [{
        "generationId__c": IDS.GEN_DECLARED,
        "generationResponseId__c": IDS.GW_RESP_DECLARED,
        "responseText__c": "I'll help you with the refund process.",
        "timestamp__c": IDS.GW_DECLARED_TS,
    }]


def _content_quality() -> List[dict]:
    return [{
        "generationId__c": IDS.GEN_DECLARED,
        "trustScore__c": 0.92,
        "qualityType__c": "NORMAL",
    }]


def _gateway_records() -> List[dict]:
    return [{
        "id__c": "gw-rec-001",
        "parent__c": IDS.GW_REQ_DECLARED,
        "sessionId__c": IDS.SID,
        "recordType__c": "RAG",
    }]


def _gateway_request_tags() -> List[dict]:
    return [
        {"id__c": "tag-001", "parent__c": IDS.GW_REQ_DECLARED,
         "tag__c": "promptTemplateDevName", "tagValue__c": "AiCopilot__ReactInitialPrompt"},
        {"id__c": "tag-002", "parent__c": IDS.GW_REQ_DECLARED,
         "tag__c": "feature", "tagValue__c": "plannerservice"},
    ]


# -----------------------------------------------------------------------------
# Public: rows + manifest
# -----------------------------------------------------------------------------


_ALL_TEMPLATES = (
    "sessions", "interactions", "messages", "moments", "participants",
    "tag_associations", "gateway_requests",
    "steps", "moment_interactions",
    "telemetry_spans", "generations", "app_generation",
    "gateway_request_tags", "gateway_responses", "gateway_records",
    "gateway_request_metadata", "gateway_request_llm",
    "feedback",
    "content_quality", "content_category", "feedback_details",
    "tag_definitions", "tag_definition_associations", "tags",
)


def make_rows() -> Dict[str, List[dict]]:
    """Return ``{dmo_name: [row, ...]}`` for all 24 DMOs.

    Empty lists for DMOs the synthetic session doesn't exercise — the
    code under test reads them by ``.get(name, [])`` and tolerates
    missing entries.
    """
    populated = {
        "sessions": _sessions(),
        "interactions": _interactions(),
        "steps": _steps(),
        "messages": _messages(),
        "participants": _participants(),
        "gateway_requests": _gateway_requests(),
        "gateway_responses": _gateway_responses(),
        "generations": _generations(),
        "content_quality": _content_quality(),
        "gateway_records": _gateway_records(),
        "gateway_request_tags": _gateway_request_tags(),
    }
    rows: Dict[str, List[dict]] = {name: [] for name in _ALL_TEMPLATES}
    rows.update(populated)
    return deepcopy(rows)


def make_manifest() -> dict:
    """Manifest shape matching what `fetch_dc.py` writes."""
    rows = make_rows()
    queries = [
        {
            "name": name,
            "row_count": len(rows[name]),
            "elapsed_ms": 50,
            "where_clause": f"ssot__AiAgentSessionId__c = '{IDS.SID}'",
        }
        for name in _ALL_TEMPLATES
    ]
    return {
        "_doc": "Per-query summary of this DC fetch run.",
        "session_id": IDS.SID,
        "org_alias": "my-org",
        "instance_url": "https://example.my.salesforce.com",
        "org_id_15": IDS.ORG_ID_15,
        "agent_api_name": IDS.AGENT_API,
        "agent_version": IDS.AGENT_VERSION,
        "session_shape": "ok",
        "started_at_utc": "2026-04-22T10:01:30.000Z",
        "finished_at_utc": "2026-04-22T10:01:32.000Z",
        "elapsed_ms": 2000,
        "queries": queries,
        "harvested_ids": {
            "interactions": [IDS.IXN_START, IDS.IXN_TURN, IDS.IXN_END],
        },
    }


# -----------------------------------------------------------------------------
# Disk materialization
# -----------------------------------------------------------------------------


def session_dir_for(data_root: Path) -> Path:
    """Compute the canonical session dir under a tmp DATA_ROOT."""
    return (
        data_root
        / IDS.ORG_ID_15
        / f"{IDS.AGENT_API}__{IDS.AGENT_VERSION}"
        / IDS.SID
    )


def write_to_disk(data_root: Path) -> Path:
    """Materialize the synthetic session under ``<data_root>/<org>/<agent>__<ver>/<sid>/``.

    Writes:
      - dc._session_manifest.json
      - dc.<name>.json for every populated DMO
      - The per-org breadcrumb at <org>/_sessions/<sid>.link

    Returns the session dir absolute path.
    """
    sdir = session_dir_for(data_root)
    sdir.mkdir(parents=True, exist_ok=True)

    # DC manifest + rows
    (sdir / "dc._session_manifest.json").write_text(
        json.dumps(make_manifest(), indent=2) + "\n"
    )
    rows = make_rows()
    for name, rs in rows.items():
        if rs:
            (sdir / f"dc.{name}.json").write_text(json.dumps(rs, indent=2) + "\n")

    # Breadcrumb so _find_session_dir's primary path resolves
    link_dir = data_root / IDS.ORG_ID_15 / "_sessions"
    link_dir.mkdir(parents=True, exist_ok=True)
    (link_dir / f"{IDS.SID}.link").write_text(
        f"../{IDS.AGENT_API}__{IDS.AGENT_VERSION}/{IDS.SID}\n"
    )

    return sdir
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall