Get Started with Agentforce Troubleshooting

Learning Objectives

After completing this unit, you’ll be able to:

Identify common categories of Agentforce behavior issues.
List six common troubleshooting checks to diagnose the problem.
Distinguish configuration issues from data, integration, and runtime issues.

Introduction

You rolled out an Agentforce agent, and now it's not doing what you expect. It picks the wrong subagent, skips an action, or gives different answers to the same question. The correction usually isn't a bug fix. Before assuming something's broken, keep in mind that most Agentforce behavior issues come from configuration, not bugs.

Unlike a traditional deterministic bot, which follows a fixed decision tree, an Agentforce agent uses a large language model (LLM) reasoning engine that attempts to determine intent. It coordinates between a library of actions while following human-generated instructions to choose what to do next.

That flexibility is powerful. It also means small gaps in setup can lead to big surprises in behavior. Unclear setup gives the model room to guess–yes, guess–and guessing is where inconsistency comes from. Simple pass or fail is giving way to context and interpretation.

Agentforce is different from the automation you're used to. A flow either passes or fails. An agent interprets. This means that troubleshooting an agent takes a different mindset than debugging a flow or a trigger.

Spot the Symptoms First

With traditional automation, when something goes wrong you usually get an error message that points to the exact line that failed.

Agents don't fail that way. Instead, they can hallucinate, which means they fill in gaps in ambiguous instructions with information that sounds plausible but isn't real.

For example, if a user asks an agent “I need a ticket,” the agent has no way of knowing whether that means a support ticket, an event ticket, or something else entirely, and it might guess wrong. Compare that to “I need to purchase a bus ticket from Chicago to St. Louis,” which gives the agent everything it needs to act correctly. Agents match the best subagent or action based on your setup. A vague description or an overlapping subagent sends the agent down the wrong path just as easily as a real error does.

Most agent troubleshooting comes down to these issues.

The agent doesn’t invoke the expected subagent or action.
Responses are incomplete, truncated, or rewritten.
Knowledge citations don’t appear.
The agent escalates to a human unexpectedly.
Identical inputs produce inconsistent outputs.

These issues are usually caused by configuration or setup rather than system errors.

Draft a Version

To begin troubleshooting, you create a draft version of your agent in Agentforce Builder. While in draft, you edit the agent and your changes are saved to the current agent version. Then, you troubleshoot the agent quickly by previewing it. In Agentforce Builder, click Preview. Choose Live Test mode when you're in a dedicated Developer org; it gives you the most complete picture of agent performance, since the agent can safely modify placeholder data. Use Set Context to specify variables that match a real customer's context, then enter a typical customer question and watch what happens.

Once you preview a conversation with your agent, you can track your agent’s reasoning and behavior in the Interaction Summary. The Interaction Summary lets you drill into the details of the interaction with trace, variables, and a little help from Agentforce. The preview experience is designed to give you all of the behind-the-scenes details of how your agent is working, so it’s easier to identify unexpected behavior and improve your agent.

Common Troubleshooting Checks

You’ve learned that the Interaction Summary is your first stop for reviewing what happened. It shows a high-level view of the steps the agent took, including reasoning steps, their LLM prompt results, and which subagent each transition routed to. Plus it gives you an AI-generated explanation of the whole process.

When you need more detail, click into any step to see the full trace data: individual agent events, the time each one took, and technical details like exactly what data filled each action's inputs and what it returned as output. This is what lets you tell the difference between an instructions problem, an action description problem, and an underlying configuration problem.

These common checks are especially useful.

Action selection: Did the subagent choose the right action? If not, add more determinism to the subagent's instructions and review the action's description and any filters. You can also try action chaining to run multiple actions in a guaranteed sequence.
Data and grounding: Look for missing or incomplete data in the response. Are you dealing with unpublished or unindexed Knowledge, or maybe missing citations? Is the underlying flow, Apex class, or prompt template actually returning correct data? Compare the response to your source of truth, and check Output Evaluation and Output Metrics in the trace, which flags whether the response is grounded, in-scope, and free of hallucinations.
Routing: Did the Agent Router select the subagent you expected? If not, review the subagent for overlap with other subagents, generic names, or vague or broad descriptions. Also check the Agent Router's instructions and the filters on the relevant transitions.
Access and context: Does the agent have the right access and context for the conversation? Check the agent’s permissions. Make sure any variables required by your logic are initialized and populated correctly. If your subagent or action is restricted by a filter, verify the filter conditions are met. Check that all dependent variables (for example, verified == True) are properly defined and currently active.
Prompting and instructions: Look for conflicting or overly complex instructions, and simplify them.
System constraints: If responses look wrong even when configuration is solid, look for token limits, execution limits, or streaming issues.

And if you want a second opinion when you’re troubleshooting these issues, you can use the built-in AI assistant in Agentforce Builder. Pro tip: When debugging agent behavior using the trace, click Ask Agentforce right from the Interaction Summary panel to get an AI-assisted analysis of the session.

You dig in more to each area of agent troubleshooting in the next units, starting with Configuration and Data Issues.

Tempo stimato

Argomenti

Hai bisogno di aiuto?

Risorse per Agentforce

Get Started with Agentforce Troubleshooting

Learning Objectives

Introduction

Spot the Symptoms First

Draft a Version

Common Troubleshooting Checks

Resources