Debugging Agentforce in production: the failures that break agents, and how to see them

The agent worked in the demo. It answered the three questions you tried, picked the right topic, called the action, returned a clean response. Then it went to production, met a real customer, and said “We couldn’t retrieve the action output. Try again or contact Salesforce Customer Support for assistance.” — or worse, confidently answered a question with information that was subtly wrong. Nobody sees a stack trace. The transcript just shows an agent that fell over, and you’re left reconstructing what it was thinking.

Debugging an agent is a genuinely different skill from debugging code, because the agent is probabilistic where code is deterministic, and its failures hide behind a polite sentence instead of an exception. But Agentforce failures are not mysterious once you know the two things every debugging session needs: a way to see what the agent actually did — which topic it chose, which action it called, what it got back — and a mental catalog of the handful of failure modes that account for most production incidents. This post is both: the reasoning tools, then the error catalog by layer, then the one trap that passes every test and breaks on go-live.

First, get eyes on the reasoning

You cannot debug what you can’t see, and the single most common mistake is arguing about why the agent did something without looking at what it did. Salesforce’s tooling for this got dramatically better over 2026, and using it is step zero of every investigation.

Start in the Agent Preview (the conversation preview inside the builder). When you send a test utterance, the center panel shows you the agent’s plan — which topic it selected and which actions it invoked to generate the response. This is the reasoning trace, and it answers the first question in any triage: did the agent misunderstand the request (wrong topic), or understand it and fail to execute (right topic, broken action)? Those are completely different bugs, and the trace tells you which one you have in one glance.

The newer Agentforce Builder deepens this with an Interaction Summary panel and a Trace tab that lay the turn out as a timeline — input, reasoning, topic transitions, actions, and output evaluation — with per-step timing so you can see where the reasoning loop actually spent its time. And if you work in Agentforce DX in VS Code, the preview lets you inspect the raw JSON exchanged between the client and the org: how the utterance was interpreted, which action was selected and why, the API calls and data transforms, and how the response was assembled. When a bug is subtle, the JSON is the ground truth.

The rule: never theorize before you’ve read the trace. Half the “the agent is broken” tickets resolve the moment you see that it chose the wrong topic — which is a design problem, not a platform one.

The error catalog, by layer

Agent failures cluster into a small number of layers. Work them in this order, because each rules out the ones below it.

Layer 1: topic misclassification — the agent understood the wrong thing

Symptom: the agent routes to the wrong topic, or refuses a request it should handle. Cause: the Atlas reasoning engine classifies each utterance into a topic by reading each topic’s classification description — and when two topics have overlapping or vaguely-written descriptions, it can’t confidently tell them apart. Too many topics makes this worse. The platform caps an agent at 15 topics, with up to 15 actions per topic, but living near that ceiling is asking for classification collisions; practitioners keep the roster well below it for exactly this reason.

Fix: one purpose per topic, and classification descriptions written as routing boundaries in the customer’s own vocabulary — what belongs here and what explicitly does not — rather than as documentation. This is the same discipline we cover in designing subagents and topics: disjoint descriptions stop the router from flip-flopping. When a misroute shows up, the overlap between two topic descriptions is the first place to look, every time.

Layer 2: the action failed to execute

Symptom: “We couldn’t retrieve the action output…”, a failed action in the trace, or a generic “I’m sorry, I can’t help with that.” The agent picked the right topic and the right action — the action itself broke. Cause: almost always one of three things — an error inside the underlying Flow or Apex, an input-variable mapping problem (the agent passed something the action didn’t expect), or wrong data types.

Fix: Salesforce’s official debugging sequence is worth following literally. Run the action’s Flow in the Flow Debugger with representative inputs and confirm it succeeds. Confirm the JSON the agent is sending matches what the Flow expects — this is where input-mapping bugs surface. Then — and this is the step people skip — log in as the Agent User and run the same flow again. If it passes as an admin and fails as the Agent User, your bug isn’t logic. It’s permissions, and you’ve just found Layer 3.

Layer 3: the permission trap that breaks on go-live

This is the one that costs teams a launch day, so it gets its own section below. Its signature error is INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY, and the reason it’s so insidious is that it passes every test you run as an admin.

Layer 4: the action ran but tripped a governor limit or a validation rule

Symptom: the action fails under real conditions after working in isolation. Cause: an Agentforce action is just Flow or Apex, which means it’s subject to the same governor limits and the same validation rules as any other automation — and those rules were often written assuming a human was filling the form. The recurring offenders:

• REQUIRED_FIELD_MISSING — the agent creates a record without a field a validation or schema requires, because it didn’t have the value a human would have typed.
• FIELD_CUSTOM_VALIDATION_EXCEPTION — an agent action collides with a validation rule built for the UI, one the agent’s path never satisfies.
• System.LimitException: Apex CPU time limit exceeded and Too many SOQL queries: 101 / Too many DML statements: 151 — chained automations or non-bulkified logic firing behind the action.

Fix: design agent actions to be bulk-safe and governor-aware from the start, exactly as you would any custom Apex action, and audit which validation rules an agent-driven path can realistically satisfy. A validation rule that assumes a human’s context is a landmine under an agent.

Layer 5: grounding returned nothing

Symptom: weak, empty, or hallucinated answers on questions the knowledge should cover. Cause: a retrieval misconfiguration — most often no search index was created, the retriever isn’t pointed at the right index, or the agent is falling back to a default retriever that searches sources you didn’t intend. Fix: grounding is a two-step setup that’s easy to half-finish. Create the search index first (with parsing and chunking tuned to your content), then create or point a retriever at that index and constrain it to the content fields you want returned. If you’re grounding on a Data Library, verify the index built before you blame the model. An empty retrieval doesn’t announce itself — it just degrades the answer.

Layer 6: it’s not the agent, it’s the data

Symptom: the agent confidently states something wrong, and the trace shows it did everything “right.” Cause: the grounding data itself is incomplete, stale, or dirty. As we’ve argued about data quality for AI, a well-built agent on bad data is just a faster way to be wrong — if the record says the wrong thing, the agent repeats it with total confidence. Fix: this one isn’t in the agent builder at all. It’s upstream, in the data foundation, and it’s why grounding quality is the strongest predictor of whether an agent actually works in production.

The Agent User: why it passes every test and fails in production

Layer 3 deserves the spotlight because it defeats the most careful testing. An Agentforce agent doesn’t run as the logged-in user. It runs as a dedicated Agent User — an autogenerated system user with its own profile and permission sets, granted access through permission sets like Access Agentforce Default Agent. That user needs CRUD and field-level access to every object and field any of its actions touch — not just the primary record, but every parent, related, and junction object referenced in a lookup, a DML, or a relationship field.

Here’s why it’s a trap. When you build and test the agent, you’re logged in as an administrator with broad access. Every action works. You demo it; it works. Then it goes live, runs as the restricted Agent User, hits an object that user can’t see, and throws INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY — on go-live day, in front of customers, for a bug that was invisible in every test you ran. The agent had the access you had, not the access it has.

The fixes are concrete:

• Test as the Agent User, not as yourself. Assign yourself the Agent User’s exact permission sets (or use login-as) and run the whole suite. This is the single highest-value habit in Agentforce QA.
• Match the Agent User’s permissions to every action’s full data footprint — including the related objects the actions traverse, which is where the cross-reference error hides.
• Run action Apex in user mode so CRUD, FLS, and sharing are enforced by the platform rather than silently assumed:

// WITH USER_MODE makes the Agent User's real access the thing that's tested,
// instead of trusting system-mode access the agent won't have in production.
List<Case> cases = [
    SELECT Id, Subject, ContactId, AccountId, Account.Name
    FROM   Case
    WHERE  Id = :caseId
    WITH   USER_MODE
];

If a query like that fails in a unit test running as the Agent User, you’ve caught the go-live bug in CI instead of in production — which is the whole point.

Watching agents in production: logs, traces, and observability

Preview and testing catch pre-launch bugs. For the ones that only appear under real traffic, Agentforce exposes a proper observability layer — and it moved from “read the transcript and guess” to structured, queryable telemetry over 2026.

Session tracing writes turn-by-turn detail into a set of Data 360 objects: AIAgentInteraction (the interaction), AIAgentSessionParticipant (who was in the session), AIAgentInteractionMessage (the messages), and AIAgentInteractionStep (each step the agent took). Enabling Enhanced Event Logs and the UiAgentInteractionEventLog object adds client-side interaction logging on top. This is what lets you reconstruct a specific bad conversation after the fact instead of trying to reproduce it.

For deeper action-level debugging, agent platform tracing (introduced in May 2026) captures every action execution as an OpenTelemetry-style trace tree in Data 360 via the TelemetryTraceSpan object — LLM calls, Flow, and Apex, each span carrying timing and status. Because the span object is self-referential (a parent-span field points back at another span’s ID), you can walk the whole tree of a single agent turn with SOQL and see exactly which nested action blew up and how long each step took:

-- The span DMO is self-referential: TelemetryParentSpanId points back at
-- another span's Id, so you can walk a full turn's tree. Confirm the exact
-- ssot__…__c field API names against your org's Data 360 model.
SELECT  ssot__Id__c, ssot__TelemetryParentSpanId__c, ssot__Status__c
FROM    ssot__TelemetryTraceSpan__dlm

Sitting above the raw telemetry, the Agentforce observability suite — Agent Analytics, Agent Optimization, and Agent Health Monitoring — gives you the aggregate view: which topics fire, where reasoning chains stall, and real-time health. Use the aggregate view to find the problem conversations and the trace tree to diagnose them.

Catch it before production: the testing layer

Almost every failure above is catchable before a customer ever sees it, if you test the agent as a system rather than typing at it. Agentforce Testing Center runs batch tests that assert, per utterance, the expected topic, expected actions, and expected response, and reports the actual topic and a pass/fail against each — which is precisely the Layer 1 (misclassification) and Layer 2 (action) detection you want, automated. Run those batches as the Agent User, gate your deployment on them, and you convert the two most common production incidents into build failures. The debugging you don’t have to do in production is the debugging you moved left into the test suite.

A triage order that works

When an agent misbehaves, resist the urge to rewrite the instructions and hope. Work the layers in order:

1. Read the trace. Wrong topic → Layer 1 (topic design). Right topic, failed action → keep going.
2. Reproduce the action in Flow Debugger as an admin. Fails → it’s action logic or input mapping (Layer 2).
3. Re-run it as the Agent User. Fails only here → permissions (Layer 3), almost always the cross-reference trap.
4. Check for governor limits and validation-rule collisions if it fails under load or on writes (Layer 4).
5. Verify the search index and retriever if answers are empty or vague (Layer 5).
6. Inspect the grounding data itself if the agent is confidently wrong with a clean trace (Layer 6).

Most incidents resolve by step three. The two that hurt most — a topic overlap you can fix in the classification description, and an Agent User permission you can grant in a permission set — are both mundane, both invisible in an admin’s testing, and both entirely preventable by reading the trace and testing as the agent instead of as yourself. That’s the whole discipline: see what the agent actually did, and test it with the access it actually has.

Understanding the basics

How do you debug an Agentforce agent?

Start with the reasoning trace in Agent Preview, which shows which topic the agent selected and which actions it invoked — that immediately tells you whether the failure is misclassification (wrong topic) or execution (right topic, broken action). For action failures, reproduce the underlying Flow in Flow Debugger, then re-run it logged in as the Agent User to isolate permission problems. For production incidents, use session tracing (the AIAgentInteraction data model), the TelemetryTraceSpan trace trees, and the Agentforce observability suite to reconstruct what happened.

Why does my Agentforce agent work in testing but fail in production?

The most common cause is the Agent User’s permissions. The agent runs as a dedicated system user, not as you, and that user needs CRUD and field-level access to every object and field its actions touch — including related and parent objects. When you test as an administrator you have broad access, so everything passes; in production the restricted Agent User hits an object it can’t see and throws INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY. Always test by assigning yourself the Agent User’s exact permission sets, and run action Apex in user mode.

Why does my Agentforce agent pick the wrong topic?

Because the Atlas reasoning engine classifies each request by reading topic descriptions, and overlapping or vaguely written descriptions make it unable to tell two topics apart — a problem that worsens as the topic count grows toward the platform maximum of 15. Fix it by giving each topic a single purpose and writing its classification description as an explicit routing boundary (what belongs here and what does not) in the customer’s vocabulary, then asserting the expected topic per utterance in Testing Center.

---

Fighting an Agentforce agent that works in the demo and falls over in production? Talk to us. Reading the trace, hardening the Agent User’s permissions, and building the test suite that catches these before go-live is a very normal week for our team.