afv-library/skills/agentforce-observe/references/stdm-schema.md

STDM Schema Reference

Data Model Object (DMO) schemas, field mappings, query patterns, and data quality notes for the Session Trace Data Model.

---

Data Hierarchy

AiAgentSession (1)
+-- AiAgentSessionParticipant (N)       -- agent planner IDs and user IDs linked to this session
+-- AiAgentInteraction (N)              -- one per conversational turn
|   +-- AiAgentInteractionMessage (N)   -- user and agent messages
|   +-- AiAgentInteractionStep (N)      -- internal steps (LLM, actions)
+-- AiAgentMoment (N)                   -- one per intent/moment in the session
|   +-- AiAgentMomentInteraction (N)    -- junction: links moments to interactions
|   +-- AiAgentTagAssociation (N)       -- junction: links moments to tags (quality scores)
|       +-- AiAgentTag (1)              -- score value (1-5)
|           +-- AiAgentTagDefinition (1)-- tag type definition
AiRetrieverQualityMetric (N)            -- RAG quality scores, linked via gateway request ID

Quality score join chain: AiAgentTagAssociation (FK AiAgentMomentId + FK AiAgentTagId) -> AiAgentTag.Value (1-5 integer). The AssociationReasonText field contains the LLM-generated reasoning for the score.

---

Key Fields

AiAgentSession (ssot__AiAgentSession__dlm)

• ssot__Id__c -- Session ID
• ssot__StartTimestamp__c / ssot__EndTimestamp__c -- Session timing -> session.duration_ms
• ssot__AiAgentChannelType__c -- Channel -> session.channel
• ssot__AiAgentSessionEndType__c -- How the session ended: USER_ENDED, AGENT_ENDED, or null -> session.end_type
• ssot__VariableText__c -- Final variable snapshot for the session -> session.session_variables

AiAgentSessionParticipant (ssot__AiAgentSessionParticipant__dlm)

• ssot__AiAgentSessionId__c -- Session this participant belongs to
• ssot__AiAgentApiName__c -- API name of the agent (primary filter field -- no SOQL needed)
• ssot__ParticipantId__c -- GenAiPlannerDefinition ID (key prefix 16j) for agents, 005... for users. May be 15-char or 18-char.

AiAgentInteraction (ssot__AiAgentInteraction__dlm)

• ssot__TopicApiName__c -- Subagent/skill that handled this turn (API field name TopicApiName maps to Agent Script subagent) -> turn.topic
• ssot__StartTimestamp__c / ssot__EndTimestamp__c -- Turn timing -> turn.duration_ms
• ssot__TelemetryTraceId__c -- Distributed tracing ID -> turn.telemetry_trace_id

AiAgentInteractionMessage (ssot__AiAgentInteractionMessage__dlm)

• ssot__AiAgentInteractionMessageType__c -- Input (user) or Output (agent) -> message.message_type
• ssot__ContentText__c -- Message text -> message.text

AiAgentInteractionStep (ssot__AiAgentInteractionStep__dlm)

• ssot__AiAgentInteractionStepType__c -- TOPIC_STEP, LLM_STEP, ACTION_STEP, SESSION_END, TRUST_GUARDRAILS_STEP -> step.step_type
• ssot__Name__c -- Step or action name -> step.name
• ssot__ErrorMessageText__c -- Error text (null if none) -> step.error
• ssot__InputValueText__c / ssot__OutputValueText__c -- Input/output data -> step.input / step.output
• ssot__PreStepVariableText__c / ssot__PostStepVariableText__c -- Variable snapshots -> step.pre_vars / step.post_vars
• ssot__GenerationId__c -- Links to GenAIGeneration__dlm -> step.generation_id (non-null on LLM_STEP)
• ssot__GenAiGatewayRequestId__c -- Links to GenAIGatewayRequest__dlm -> step.gateway_request_id (non-null on LLM_STEP)

Einstein Audit & Feedback DMOs (joined via getLlmStepDetails())

GenAIGeneration__dlm -- LLM generation records:

• generationId__c -- Join key to ssot__GenerationId__c on the step DMO
• responseText__c -- The full LLM response text -> LlmStepDetail.llm_response

GenAIGatewayRequest__dlm -- Raw gateway requests sent to the LLM:

• gatewayRequestId__c -- Join key to ssot__GenAiGatewayRequestId__c on the step DMO
• prompt__c -- Full prompt text including system instructions -> LlmStepDetail.prompt

These two DMOs are only populated when Einstein Audit & Feedback is enabled in the org's Data Cloud setup.

AiAgentMoment (ssot__AiAgentMoment__dlm)

Each moment represents a distinct user intent within a session. One session may have multiple moments.

• ssot__Id__c -- Moment ID
• ssot__AiAgentSessionId__c -- FK to AiAgentSession
• ssot__StartTimestamp__c / ssot__EndTimestamp__c -- Moment timing -> MomentData.duration_ms
• ssot__RequestSummaryText__c -- LLM-generated summary of user intent -> MomentData.request_summary
• ssot__ResponseSummaryText__c -- LLM-generated summary of agent response -> MomentData.response_summary
• ssot__AiAgentApiName__c -- Agent API name that handled this moment
• ssot__AiAgentVersionApiName__c -- Agent version API name

AiAgentMomentInteraction (ssot__AiAgentMomentInteraction__dlm)

Links moments to the interactions (turns) they span. One moment may cover multiple turns.

• ssot__Id__c -- Junction record ID
• ssot__AiAgentMomentId__c -- FK to AiAgentMoment
• ssot__AiAgentInteractionId__c -- FK to AiAgentInteraction
• ssot__StartTimestamp__c -- When this moment-interaction link was created

AiAgentTagAssociation (ssot__AiAgentTagAssociation__dlm)

The key junction table for quality scores. Links a moment to a tag (score 1-5) with LLM reasoning.

• ssot__Id__c -- Association ID
• ssot__AiAgentMomentId__c -- FK to AiAgentMoment
• ssot__AiAgentTagId__c -- FK to AiAgentTag (join to get the score value)
• ssot__AiAgentSessionId__c -- FK to AiAgentSession (denormalized for efficient filtering)
• ssot__AiAgentInteractionId__c -- FK to AiAgentInteraction
• ssot__AiAgentTagDefinitionAssociationId__c -- FK to TagDefinitionAssociation
• ssot__AssociationReasonText__c -- LLM-generated reasoning for the quality score -> MomentData.quality_reasoning
• ssot__IsPassed__c -- Whether the moment passed quality threshold

Quality score query: TagAssociation JOIN Tag ON TagId -> Tag.Value gives the 1-5 integer score per moment.

AiAgentTag (ssot__AiAgentTag__dlm)

Contains the 5 quality score levels (1-5). Each tag has a numeric value.

• ssot__Id__c -- Tag ID
• ssot__AiAgentTagDefinitionId__c -- FK to tag definition
• ssot__Value__c -- Score value (e.g. "1", "2", "3", "4", "5") -> MomentData.quality_score
• ssot__Description__c -- Score description (null in current orgs)
• ssot__IsActive__c -- Whether this tag is active

AiAgentTagDefinition (ssot__AiAgentTagDefinition__dlm)

Defines tag categories per agent. Each agent gets its own tag definition.

• ssot__Id__c -- Tag Definition ID
• ssot__Name__c -- Display name (e.g. "Optimization Request Category")
• ssot__DeveloperName__c -- API name (e.g. "AIE_Request_Category_MyServiceAgent")
• ssot__DataType__c -- Data type (e.g. "Text")
• ssot__EngineType__c -- Engine that generates the tags
• ssot__Status__c -- Definition status

AiRetrieverQualityMetric (ssot__AiRetrieverQualityMetric__dlm)

Per-retrieval quality metrics for agents using knowledge retrieval. Links to sessions via gateway request ID.

• ssot__Id__c -- Metric ID
• ssot__AiGatewayRequestId__c -- FK to GenAIGatewayRequest
• ssot__AiRetrieverRequestId__c -- Retriever request ID
• ssot__RetrieverApiName__c -- API name of the retriever
• ssot__UserUtteranceText__c -- User utterance that triggered retrieval
• ssot__AgentGeneratedResponseText__c -- Agent response text
• ssot__FaithfulnessRelevancyScoreNumber__c -- Faithfulness score (0-1)
• ssot__AnswerRelevancyScoreNumber__c -- Answer relevance score (0-1)
• ssot__ContextPrecisionScoreNumber__c -- Context precision score (0-1)

Only populated when the agent uses knowledge retrieval actions. May have 0 rows if the agent has no RAG actions.

---

TRUST_GUARDRAILS_STEP

A safety/compliance step that measures whether the agent's response followed its instructions:

• step.name is typically InstructionAdherence
• step.output is a Python-style dict string (not JSON). Actual format:

  {'name': 'InstructionAdherence', 'value': 'HIGH', 'explanation': 'This response adheres to the assigned instructions.'}
  

  Check for adherence by searching for 'value': 'LOW' in the output string.
• step.input contains the raw input_text and output_text that were evaluated
• step.error may contain the literal string "None" (not a real error)
• Does not count toward action_error_count

---

Data Quality Notes

NOT_SET sentinel. Data Cloud uses "NOT_SET" for null/absent values. AgentforceOptimizeService strips this sentinel -- any field returning null in the JSON should be treated as absent.

TRUST_GUARDRAILS_STEP error field. May have the Python string "None" in the error field. This is not a real error -- treat it as absent. action_error_count is only incremented for ACTION_STEP errors.

Null end_time / duration_ms. Sessions and turns may have null for end_time when no session-end event was recorded. This is common and does not indicate a problem.

LLM_STEP input/output format. The input and output fields on LLM_STEP contain raw Python dict strings (the internal LlamaIndex representation), not valid JSON. Do not attempt to JSON.parse() these values. Only ACTION_STEP input/output is structured JSON.

Participant ID format inconsistency. The ssot__AiAgentSessionParticipant__dlm DMO stores ssot__ParticipantId__c as either 15-char or 18-char Salesforce IDs, inconsistently. AgentforceOptimizeService.resolvePlannerIds() automatically handles both formats.

---

Data Space Name

Always run Phase 0 first to discover the correct Data Space name for the org. Use sf api request rest "/services/data/v63.0/ssot/data-spaces" -o <org> (no --json flag -- unsupported on this beta command). Never assume 'default' without checking -- it is only a fallback if the API call fails.

---

Agent Name Resolution Reference

The only Salesforce metadata object that should be queried directly is GenAiPlannerDefinition -- used exclusively for agent name resolution in the Routing step.

Object	Purpose	When to query
GenAiPlannerDefinition	The agent definition	Routing step only -- to resolve MasterLabel, DeveloperName, and Id
DataKnowledgeSpace	Knowledge base container	Phase 1.5b Step 5 only -- if knowledge gaps are detected

Do NOT query these objects directly -- use the .agent file instead:

• GenAiPluginDefinition (subagents) -- read from .agent file subagent: blocks
• GenAiPluginInstructionDef (instructions) -- read from .agent file reasoning: instructions: blocks
• GenAiFunction (actions) -- read from .agent file reasoning: actions: blocks

The .agent file is the single source of truth. All fixes should be applied to it and deployed via the Phase 3 deployment chain.