Troubleshoot Agentforce Agent Behavior Using Session Tracing Data Model

Overview

The Session Tracing Data Model (STDM) captures telemetry for Agentforce sessions in Data 360, providing visibility into agent execution and runtime behavior. This guide helps administrators and developers use STDM to trace session execution, monitor variable updates, inspect user and agent interactions, investigate action failures, review LLM prompts and responses, identify recurring execution patterns, and discover opportunities to optimize prompts, actions, subagents, and instructions. It also introduces the core STDM objects, explains their relationships, and provides practical SQL query examples and troubleshooting workflows to help diagnose issues and improve Agentforce behavior.

Without observability: debugging is guesswork, tuning is slow, quality is risky, cost spikes go unnoticed, and trust erodes. With Agent Session Tracing, you get clear, structured logs for every session and interaction — facts, not guesses.

When to Use This Guide

Use this guide if you experience issues such as:

• Agent selects the wrong topic
• Expected action isn’t executed
• Variables aren’t populated correctly
• Agent responses are inconsistent
• Prompt Templates don’t behave as expected
• Agent loops between topics
• Unexpected conversation flow
• Action execution errors
• Performance issues (slow responses, long interaction times)

Setup & Prerequisites

Enable Session Tracing

1. Navigate to Setup → Search “Agentforce Session Tracing”.
2. Enable the following:
   • Einstein Generative AI
   • Einstein Trust Layer
   • Einstein Audit, Analytics, and Monitoring Setup
   • Agentforce Session Tracing (main toggle)

Reference: Enable Agentforce Session Tracing — Prerequisites, permissions, troubleshooting

SSOT Package Version

Minimum required: Version 1.130+

To check your version:

1. Setup → Installed Packages.
2. Search for “SSOT”.
3. Verify the version is ≥ 1.130.

If the version is too old, DMOs won’t appear in the Query Editor even if DLOs are visible.

DLO to DMO Mapping

After enabling session tracing:

1. DLOs (Data Lake Objects) are provisioned first and serve as the raw data storage layer.
2. Map each DLO to a DMO (Data Model Object) to make the data queryable.
   • Example: Map the AiAgentSession DLO → ssot__AiAgentSession__dlm DMO.

If DMOs are not visible, check the SSOT version and the DLO mapping.

Accessing STDM Queries

• Navigate to Data Cloud → Query Editor.
• Use ANSI SQL syntax.
• All tables follow the ssot__<ObjectName>__dlm naming convention.
• The user needs the Data Cloud Query Access permission.
• If you receive an error such as table "<table_name>" does not exist in Query Editor. Please refer Data 360: Error "table ... does not exist" in Data Explorer or Query Editor

Before You Begin

Before reviewing Session Trace data, verify that:

• Session Tracing is enabled (see Setup & Prerequisites).
• You have reproduced the issue.
• You have the Session ID for the affected conversation.
• The agent configuration has been saved and published.
• Recent configuration changes have been deployed.

How to find a Session ID: Run Query 3 scoped to a recent time window to browse sessions and grab a Session ID. You can also find it from the Conversation record in the Salesforce UI, or by querying the Messages table (Query 7) filtered by a recent date.

Understanding the STDM

The Five Core Tables

All objects use the ssot__ prefix (Standard Object Type) and end with __dlm. These are part of the Standard Data Cloud Object Model installed with Data 360 SSOT.

STDM Object Relationships

Session (1)
├── Participants (N)        [1-to-many: one session, many participants]
└── Interactions (N)        [1-to-many: one session has many turns]
     ├── Messages (N)       [1-to-many: one interaction has many messages]
     └── Steps (N)          [1-to-many: one interaction has many steps]
            └── GenAIGeneration (via ssot__GenerationId__c)
                  └── GenAIGatewayRequest / Response (for LLM calls)

The STDM integrates seamlessly with the Einstein Audit and Feedback Data Model-the foundational model for all Generative Audit and Feedback use-cases across Salesforce. Steps link to Einstein Audit records via ssot__GenerationId__c and ssot__GenAiGatewayRequestId__c.

Step Types Reference

Quick Troubleshooting Guide

Common Troubleshooting Queries

The following queries help diagnose the most common Agentforce configuration and runtime issues. Each query includes:

• Use case — when to use the query.
• SQL query — an example you can run in the Data Cloud Query Editor.
• What this shows — the information returned by the query.
• Configuration insights — how to interpret the results and identify opportunities to improve your Agentforce configuration.

Note: In every session-scoped query below, replace <SESSION_ID> with the Session ID of the conversation you’re investigating.

Query 1 — Get Complete Session Execution Flow

Use case: Trace all execution steps for an Agentforce session in chronological order. This query provides a complete view of how the agent processed the conversation, including topic selection, action execution, variable updates, LLM reasoning, and any runtime errors.

SELECT
  ssot__Name__c,
  ssot__AiAgentInteractionStepType__c,
  ssot__InputValueText__c,
  ssot__OutputValueText__c,
  ssot__PreStepVariableText__c,
  ssot__PostStepVariableText__c,
  ssot__ErrorMessageText__c,
  ssot__StartTimestamp__c
FROM "ssot__AiAgentInteractionStep__dlm"
WHERE ssot__AiAgentInteractionId__c IN (
  SELECT ssot__Id__c
  FROM "ssot__AiAgentInteraction__dlm"
  WHERE ssot__AiAgentSessionId__c LIKE '%<SESSION_ID>%'
)
ORDER BY ssot__StartTimestamp__c ASC;

What this shows:

• Every action/step executed (topic selection, action calls, LLM reasoning)
• Inputs passed to each step
• Outputs returned
• Variable state before/after each step
• Runtime or validation errors, if any
• The complete execution timeline for the session

Configuration insights:

• Which actions were called vs. skipped (check if expected actions fired)
• Variable transformations (did action outputs populate expected variables?)
• Error patterns (action input validation failures → check required input variable references)

Query 2 — Track Variable Updates Across a Session

Use case: Review how variables change throughout a session to diagnose missing, incorrect, or unexpected values.

SELECT
  ssot__PreStepVariableText__c,
  ssot__PostStepVariableText__c,
  ssot__StartTimestamp__c
FROM "ssot__AiAgentInteractionStep__dlm"
WHERE
  ssot__AiAgentInteractionStepType__c = 'VARIABLE_UPDATE_STEP'
  AND ssot__AiAgentInteractionId__c IN (
    SELECT ssot__Id__c
    FROM "ssot__AiAgentInteraction__dlm"
    WHERE ssot__AiAgentSessionId__c LIKE '%<SESSION_ID>%'
  )
ORDER BY ssot__StartTimestamp__c ASC;

What this shows:

• Variable state at each update point
• When variables were set/cleared
• Variable flow through the session

Configuration insights:

• Missing variables → check if the prior action’s output variable mapping is correct
• Variables never set → the action may not have been called (topic selection issue)
• Variables cleared unexpectedly → check topic transition logic

Query 3 — Get Initial Session Variables

Use case: Review the variables and metadata available when the Agentforce session begins (context variables).

SELECT
  ssot__VariableText__c,
  ssot__StartTimestamp__c,
  ssot__EndTimestamp__c,
  ssot__AiAgentSessionEndType__c
FROM "ssot__AiAgentSession__dlm"
WHERE ssot__Id__c LIKE '%<SESSION_ID>%';

What this shows:

• Initial context (user profile, session state, pre-populated data)
• Session duration
• Session completion status

Configuration insights:

• Check if required context variables exist (e.g., userId, accountId)
• Verify session-level data was passed correctly from end users

Query 4 — Find Failed Actions

Use case: Identify actions that failed during execution and review the associated error messages, inputs, and timestamps to determine the root cause.

SELECT
  ssot__Name__c,
  ssot__AiAgentInteractionStepType__c,
  ssot__InputValueText__c,
  ssot__ErrorMessageText__c,
  ssot__StartTimestamp__c
FROM "ssot__AiAgentInteractionStep__dlm"
WHERE
  ssot__ErrorMessageText__c IS NOT NULL
  AND ssot__ErrorMessageText__c <> 'NOT_SET'
  AND ssot__AiAgentInteractionId__c IN (
    SELECT ssot__Id__c
    FROM "ssot__AiAgentInteraction__dlm"
    WHERE ssot__AiAgentSessionId__c LIKE '%<SESSION_ID>%'
  )
ORDER BY ssot__StartTimestamp__c ASC;

What this shows:

• Actions that failed during execution
• Validation, Apex, Flow, or runtime error messages
• Inputs provided to the failed action

Configuration insights:

• Validation errors → check action input descriptions; add required input variable references
• Missing input → check if a prior action populated the required variables
• Repeated errors → improve instructions to collect required data before the action call

Query 5 — Review LLM Prompts and Responses (Einstein Audit)

Use case: Review the prompts sent to the LLM and the corresponding responses to understand how the model selected topics, chose actions, or generated responses.

SELECT
  gr."promptTemplateDevName__c",
  gr."prompt__c",
  gen."responseText__c",
  gr."timestamp__c"
FROM "GenAIGatewayRequest__dlm" gr
JOIN "GenAIGatewayResponse__dlm" gresp
  ON gr."gatewayRequestId__c" = gresp."generationRequestId__c"
JOIN "GenAIGeneration__dlm" gen
  ON gresp."generationResponseId__c" = gen."generationResponseId__c"
WHERE gr."sessionId__c" LIKE '%<SESSION_ID>%'
ORDER BY gr."timestamp__c" ASC
LIMIT 100;

Note: The GenAIGatewayRequest__dlm, GenAIGatewayResponse__dlm, and GenAIGeneration__dlm tables are part of the Einstein Audit and Feedback Data Model and use a different naming convention (no ssot__ prefix). These are Einstein Audit tables that join to STDM via ssot__GenerationId__c and ssot__GenAiGatewayRequestId__c on the Step object.

What this shows:

• The Prompt Template used (e.g., Topic Classifier, Action Selector)
• The complete prompt sent to the LLM
• The generated response returned by the LLM (selected topic, chosen action, reasoning)
• The time each LLM request occurred

Configuration insights:

• Check if topic descriptions appeared in the prompt correctly
• See which topics the LLM considered (classification reasoning)
• Verify action descriptions are clear in the prompt context
• Identify if the LLM misinterpreted instructions

Query 6 — Find All Sessions with a Specific Error Pattern

Use case: Identify recurring errors across multiple sessions to help detect common configuration issues or trends.

SELECT
  ints.ssot__AiAgentSessionId__c,
  COUNT(steps.ssot__Id__c) AS error_count,
  MAX(steps.ssot__ErrorMessageText__c) AS sample_error
FROM "ssot__AiAgentInteraction__dlm" ints
JOIN "ssot__AiAgentInteractionStep__dlm" steps
  ON ints.ssot__Id__c = steps.ssot__AiAgentInteractionId__c
WHERE
  steps.ssot__ErrorMessageText__c LIKE '%required field missing%'
  AND steps.ssot__StartTimestamp__c >= CURRENT_DATE - INTERVAL '7' DAY
GROUP BY ints.ssot__AiAgentSessionId__c
HAVING COUNT(steps.ssot__Id__c) > 0
ORDER BY error_count DESC
LIMIT 50;

What this shows:

• Sessions affected by the specified error
• Frequency of the error
• A sample error message for each session

Configuration insights:

• Widespread “required field missing” → add required input variable references to the action
• Repeated validation errors → improve the action description to clarify expected inputs

Query 7 — Get User Messages and Agent Responses

Use case: Review the conversation history to understand how the user interacted with the agent and how the agent responded throughout the session.

SELECT
  msg.ssot__AiAgentInteractionMessageType__c,   -- 'Input' (user) or 'Output' (agent)
  msg.ssot__ContentText__c,
  msg.ssot__MessageSentTimestamp__c
FROM "ssot__AiAgentInteractionMessage__dlm" msg
WHERE msg.ssot__AiAgentInteractionId__c IN (
  SELECT ssot__Id__c
  FROM "ssot__AiAgentInteraction__dlm"
  WHERE ssot__AiAgentSessionId__c LIKE '%<SESSION_ID>%'
)
ORDER BY msg.ssot__MessageSentTimestamp__c ASC;

What this shows:

• User messages
• Agent responses
• Message timestamps
• The chronological flow of the conversation

Configuration insights:

• Check if the agent asked for information it already had (instruction quality)
• Verify the agent’s response tone matches global_instructions
• Identify if the agent hallucinated (response not based on action output)

Query 8 — Find Sessions with a Specific Step Type

Use case: Identify when a specific topic or action was executed and understand how frequently it is used across sessions.

SELECT
  ints.ssot__AiAgentSessionId__c,
  steps.ssot__Name__c,
  steps.ssot__StartTimestamp__c
FROM "ssot__AiAgentInteraction__dlm" ints
JOIN "ssot__AiAgentInteractionStep__dlm" steps
  ON ints.ssot__Id__c = steps.ssot__AiAgentInteractionId__c
WHERE
  steps.ssot__Name__c = 'OrderTracking'
  AND steps.ssot__StartTimestamp__c >= CURRENT_DATE - INTERVAL '7' DAY
ORDER BY steps.ssot__StartTimestamp__c DESC
LIMIT 100;

What this shows:

• Sessions where the specified topic or action was executed
• When the topic or action was invoked
• Usage frequency over the selected time period

Configuration insights:

• Action never called → check if the topic description includes trigger phrases
• Action called too often → check for overlap with other topics (add boundary clauses)

Query 9 — Step Duration (Performance Debugging)

Use case: Find which individual step is the bottleneck — useful for slow action, Apex, or LLM calls.

SELECT
  ssot__AiAgentInteractionId__c AS InteractionId,
  ssot__Id__c AS StepId,
  ssot__Name__c AS StepName,
  DATEDIFF('second', ssot__StartTimestamp__c, ssot__EndTimestamp__c) AS Duration_Seconds
FROM "ssot__AiAgentInteractionStep__dlm"
ORDER BY Duration_Seconds DESC
LIMIT 100;

Configuration insights:

• Long-running steps → consider optimizing the Apex/Flow/RAG service behind the action
• Consistently slow LLM_REASONING_STEP → review prompt length, reduce context size

Query 10 — Interaction/Turn Duration & Time-To-First-Response (TTFR)

Use case: Find how long each turn took and measure Time-To-First-Response (TTFR) — a vital metric because it can indicate systemic lags in underlying systems such as RAG.

SELECT
  ssot__Id__c AS InteractionId,
  ssot__AiAgentSessionId__c AS SessionId,
  DATEDIFF('second', ssot__StartTimestamp__c, ssot__EndTimestamp__c) AS Duration_Seconds
FROM "ssot__AiAgentInteraction__dlm"
ORDER BY Duration_Seconds DESC
LIMIT 100;

Query 11 — Interaction Count per Session (Loop Detection)

Use case: Find sessions with an unusually high number of turns — a strong signal the agent is looping between topics.

SELECT
  ssot__AiAgentSessionId__c AS SessionId,
  COUNT(*) AS InteractionCount
FROM ssot__AiAgentInteraction__dlm
GROUP BY ssot__AiAgentSessionId__c
ORDER BY InteractionCount DESC
LIMIT 50;

Configuration insights:

• High interaction count → run Query 1 on the session, look for repeated TRANSITION_STEP or TOPIC_CLASSIFICATION_STEP entries
• Looping → topic descriptions likely overlap, add “DO NOT use for…” boundary clauses

Query 12 — Who Joined the Session (Participants)

Use case: Confirm which agent and user were involved in a session. Useful when verifying the correct agent was invoked or when debugging multi-agent scenarios.

SELECT
  ssot__AiAgentSessionId__c AS SessionId,
  ssot__ParticipantId__c AS ParticipantId
FROM ssot__AiAgentSessionParticipant__dlm
WHERE ssot__AiAgentSessionId__c LIKE '%<SESSION_ID>%'
ORDER BY ssot__AiAgentSessionId__c;

Query 13 — End-to-End Join (All Five DMOs)

Use case: Full session dump joining all five core objects — use this when you need a complete picture of a specific session for export or deep analysis.

SELECT *
FROM
  ssot__AiAgentSession__dlm,
  ssot__AiAgentInteraction__dlm,
  ssot__AiAgentInteractionStep__dlm,
  ssot__AiAgentInteractionMessage__dlm,
  ssot__AiAgentSessionParticipant__dlm
WHERE
  ssot__AiAgentInteractionStep__dlm.ssot__AiAgentInteractionId__c = ssot__AiAgentInteraction__dlm.ssot__Id__c
  AND ssot__AiAgentInteraction__dlm.ssot__AiAgentSessionId__c = ssot__AiAgentSession__dlm.ssot__Id__c
  AND ssot__AiAgentInteractionMessage__dlm.ssot__AiAgentInteractionId__c = ssot__AiAgentInteraction__dlm.ssot__Id__c
  AND ssot__AiAgentSessionParticipant__dlm.ssot__AiAgentSessionId__c = ssot__AiAgentSession__dlm.ssot__Id__c
  AND ssot__AiAgentSession__dlm.ssot__Id__c = '<SESSION_ID>';

How to Interpret Your Results

The SQL queries in this guide provide detailed insight into Agentforce runtime behavior. Use the following table to help interpret common findings.