Profiling Atlas: How I Debug and Audit the Agentforce Reasoning Lifecycle
When a traditional Apex trigger or Flow fails, we open up Developer Console, set our debug logs, and read the execution path. But when an autonomous agent goes off the rails, developers often throw their hands up in frustration, treating the system like an unpredictable black box.
If you don't know how to trace the exact chain of thought that led to an autonomous decision, you can't confidently deploy your agentic networks to production.
To round out our Agentforce architecture series, I’m pulling back the curtain on how I profile the Atlas Reasoning Engine. By leveraging the brand-new Agent Platform Tracing framework, we can capture every LLM step, Flow orchestration, and Apex invocation as structured, queryable OpenTelemetry trace trees inside Data 360.
Here is my masterclass blueprint for debugging non-deterministic AI execution paths with deterministic precision.
The Reality of the Reasoning Trace
Every conversation turn inside Agentforce isn't just a simple API call; it's a dynamic lifecycle. The Atlas engine evaluates the user's intent at the start_agent entry point, maps it to specific topics, selects a tool, runs it, checks the result, and loops until it satisfies the core objective.
When an execution crashes or returns a completely wild response, the issue usually boils down to one of two root causes:
Semantic Misalignment: The LLM interpreted a tool’s output payload as a failure and initiated an incorrect self-correction loop.
Permission Silent Drops: The agent invoked a custom action, but the underlying
Custom Einstein Agent Userprofile lacked FLS (Field Level Security) or CRUD access, causing a silent transactional rollback.
To find these bugs without guessing, we have to transition to telemetry-driven debugging.
Step 1: Real-Time Diagnostics via VS Code & the Agent Tracer
For local scratch org and sandbox development, I completely bypass the standard browser UI and rely on Agentforce DX (AFDX) inside VS Code.
By starting an interactive preview conversation using the Salesforce CLI with specialized flags, you can generate synchronized Apex debug logs alongside the raw JSON execution traces.
# Starting a live-action preview session that automatically captures Apex debug loops
sf agent preview --api-name My_Enterprise_Billing_Agent --use-live-actions --apex-debug --output-dir ./agent-traces
When you use the Agent Tracer panel in VS Code during a simulated conversation, you receive a millisecond-by-millisecond breakdown of the interaction. You can view the exact assembled prompt schema—including Global Instructions, YAML/JSON toggles, and the data flow matrix—allowing you to see exactly what context was handed to the LLM right before it made a wrong turn.
Step 2: Production Observability with Agent Platform Tracing
While local tracing is perfect for development, debugging live enterprise systems at scale requires global instrumentation. This is where Agent Platform Tracing changes the game.
When enabled under Setup → Agent Platform Tracing, the platform automatically captures every single action execution as a telemetry "span" and streams it natively into Data 360. Each child span logs its parent span ID, allowing us to reconstruct the exact hierarchical execution sequence of a non-deterministic loop.
A typical trace tree for a failing autonomous action looks like this:
[OK] run.interaction (96afcfefaa6fbfe9) — 2,430ms
└── [OK] run.llmstep (9939b8bc33d12bfa) — 167ms
└── [OK] run.topic.BillingServiceTopic — 3ms
└── [OK] run.llmstep (b3595456464fbe93) — 1,341ms
└── [ERROR] run.action.Update_Invoice_Fields — 481ms
└── [ERROR] INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY
Looking at this span tree, we don't have to guess if the LLM hallucinated. We can see with absolute mathematical proof that the agent chose the correct tool (Update_Invoice_Fields), but the transaction hard-failed at millisecond 2430 because of a platform profile security violation.
Step 3: Querying Traces Natively Using SOQL
Because these execution paths are offloaded straight into Data 360 Data Model Objects (DMOs), you don’t need an expensive third-party logging tool to audit your AI. You can write standard SOQL queries using the Single Source of Truth (ssot__) data lake prefix to profile your agent’s performance over time.
Here is the exact diagnostic query I run to isolate which custom actions are throwing the most errors or creating the highest transaction latency across the system:
SELECT ssot__OperationName__c,
AVG(ssot__DurationNumber__c) AvgDuration,
MAX(ssot__DurationNumber__c) MaxDuration,
COUNT(Id) SpanCount
FROM ssot__TelemetryTraceSpan__dlm
WHERE ssot__StartDateTime__c > 2026-05-01T00:00:00Z
GROUP BY ssot__OperationName__c
LIMIT 20
By scheduling this analytical data stream or exposing it via a Slack workspace connection, your operations team can ask natural language questions like "Which sub-agent is responsible for the most errors this week?" and receive instantaneous root-cause analysis based on live trace data.
🧠 Codeforce Chronicles Technical Quiz
Q1: Where does Agent Platform Tracing store its OpenTelemetry span data for long-term historical analysis?
A) In the browser's local cache storage memory.
B) Inside Data 360 Data Model Objects (DMOs) using the single source of truth (
ssot__) prefix.C) Directly within standard Salesforce Debug Logs under the Developer Console.
Q2: If an Agentforce autonomous agent repeatedly skips a custom action you explicitly instructed it to run, what is the first step you should take to diagnose the issue?
A) Delete the entire agent and rewrite the system prompt from scratch.
B) Review the interaction trace via the Agent Tracer or VS Code Agentforce DX preview to inspect the exact assembled prompt schema and tool routing choices.
C) Increase the foundational LLM's token context window manually.
🚀 Join the Codeforce Chronicles Movement!
Stop treating AI like magic and start treating it like architecture. Telemetry and structured observability are the final frontiers for deploying bulletproof, production-grade autonomous networks.
🎥 Subscribe to my YouTube Channel: I pull back the curtain on live tracing, reading Data 360 spans, and debugging Agentforce sessions in VS Code! 👉 https://www.youtube.com/@CodeForceChronicles
🌐 Follow this Blog: Hit the Follow button on the sidebar to get technical blueprints delivered straight to your dashboard!
Drop your quiz answers in the comments section! How are you profiling and auditing your Atlas Reasoning Engine lifecycles? 👇