6 Tips To Help You Troubleshoot Agentforce With Confidence

By Joshua Birk | June 4, 2025

If you’ve ever built a flow, you know when something doesn’t work—and you go into detective mode. With Agentforce, that same instinct applies, but the way we think about troubleshooting common issues is evolving.

Agentforce represents a new paradigm in human-computer interactions. The applications we use day in and day out operate under the basic concepts of a graphical user interface, a data model, and an application layer to handle the logic. Plenty of things can malfunction in between those three core areas, but the concepts behind have remained largely unchanged.

Agentforce, on the other hand, utilizes a conversational interface that interacts with a reasoning engine that’s attempting to determine intent, coordinating between a library of actions while following human-generated instruction and implied roles.

This new paradigm changes how we think about using and troubleshooting agents. In many ways, we’re moving past a world of simple pass or fail, and into a universe of context and interpretation.

In this post, we’ll break down some common issues with agents, with practical tips for identifying what went wrong and getting your agents back on track.

Context is king

First and foremost, whenever you give artificial intelligence (AI) instructions of any kind, remember: The more context you provide, the more the reasoning engine has to work with. Consider the following statement.

I need a ticket.

AI reads a sentence by breaking it apart and attempting to find the important parts to form a response. If the parts it finds are too ambiguous, then you invite the AI to make up a realistic sounding response which could also be inaccurate. This is where what people call hallucinations come from—the AI tries to fill in the gaps in order to fulfill the request. Now, consider this statement.

I need to purchase a bus ticket from Chicago to St. Louis.

Phrasing it this way provides more context about intent, the type of ticket we mean, and what we need it for. Context is important for any text you give Agentforce—user prompts, prompt templates, instructions, etc. You’ll want to keep this in mind whenever you work with agents.

Tip 1: Check your context, emphasis, and descriptions

One of the earliest hallucinations I got from Prompt Builder was when the response was reporting on an account’s passport number. This was a head scratcher because my accounts don’t have passports. The fix, however, was simple.

Instead of:

{!Account.Id}

I made it:
Account record Id ({!Account.Id})

Another way to help ease confusion involves your description fields. As admins, we know that a handy description field is great for humans, but it’s just as useful to Agentforce. This is especially true when the Atlas reasoning engine is trying to determine which actions to use and how to use them. If your prompt templates or instructions aren’t performing as expected, ask these questions.

Did you provide a role?
Did you provide a context outside of just the field or input reference?
Did you provide instructions for variances in data; for instance, when a related field, object, or list might be blank?
Did you specify things like tone and brevity?
Were you specific in the kind of formatting you want the response to have?

Tip 2: Solve unwanted behavior with clear instructions

Speaking of dealing with ambiguity, one of the most powerful tools in your toolkit for controlling how an agent performs is the instructions associated with your topic. Remember that your topics should be associated with a specific role or task. Within that task, your users will try responses in a way that might seem natural to them but will be confusing to the reasoning engine.

A classic example that we’ve found on the Admin team is a simple one: What does “Mine” or “My” mean? If the engine is just looking at the metadata, the simplest answer is probably the owner of the record. While that’s pretty standard for Salesforce in general, in our case, “Mine” or “My” is actually referring to a related object, Contributor. Instead of attempting to fix this with a flow, we added the following as an instruction.

“My” or “Mine” might refer to the Owner of a record or a contact on a Contributor on the Content record

Similarly, we added instructions to define things like “blog” or “podcast” as a record type of Content instead of objects in their own right.

Tip 3: Focus on your inputs and outputs

So far we’ve talked specifically about tweaking AI behavior with simple text, but a lot of agent customization comes down to building flows. Flows are an incredibly powerful way to create custom actions. When translated to a custom action for your agent’s topic, your flow is the logic in between the inputs and outputs defined in the action.

Be very specific about how the agent will interpret the prompts, hand that data over to your flow, and then have Flow do its magic to hand off the response in the end. Some things to consider:

When in doubt, assume the agent is going to use text as an input.
However, remember that data types will have to follow the custom actions.
Is it the right input? For example, the agent might have the contact name, but to run the flow, you must have the contact ID. If you don’t have it, you need to get it.
If you don’t see an input when building out the corresponding action, it’s probably a data type the agent won’t support.
When returning a list of variables, do not simply let Salesforce pick all the fields. It won’t break anything, but your agent will likely create a list with a lot of unhelpful information.
When possible, give your inputs a default value that you can rely on in case the agent (or user, more likely) doesn’t offer the information.

Tip 4: Plan Tracer is your friend

Plan Tracer is the middle section of Agent Builder that shows you the following information.

Which topic was chosen
Which actions are available to the topic
Which actions are being chosen
The JSON data of the inputs and outputs of those actions

The dynamic nature of agents can require a little detective work to determine what’s going on behind the scenes, but the information the Plan Tracer shows can help solve unreliable results. You’ll find the tips above to be easier to follow by examining the Plan Tracer. Let’s talk about some common scenarios and how to solve them.

The wrong topic is chosen. This is probably because the instructions between the topics are too vague, especially when describing out the role. If they aren’t complete or distinct enough, then the agent will feel obliged to go the wrong way.

Actions are missing. As in, you added the action to the topic but the Plan Tracer doesn’t list it with the topic. This is almost certainly a permissions issue. For example, if the action requires Apex, is the class allowed by the profile?

The wrong action is chosen. Similar to the first scenario, double-check your descriptions and instructions. Remember, you can guide the topic toward actions within the instructions as well. The other thing I’ve seen is actions that aren’t inherently flawed but just too similar, and that can be between standard and custom actions. Consider whether you need the competing action, or if it can be removed or moved to a different topic.
The JSON has the wrong information. This is the inverse of the last tip. Consider things like: Is the prompt being parsed correctly or can instructions help them work better? Does the JSON match what’s happening in Flow Debug and, if so, is Flow throwing an error or misbehaving? Are the data types right? If not, is there something different based on how the records are being tested? Remember, different record types might have different rules around them.

While Plan Tracer is your friend and the scope of this post is on day-to-day troubleshooting tips, we would be remiss not to mention the more robust Agentforce Testing Center, as demonstrated by Principal Developer Advocate Philippe Ozil. This tool allows you to create CSVs to describe the use case you’re expecting to come from the agent, run it with the suite, and compare it with the actual outcome.

Tip 5: Remember your training

This is mostly about using flows for custom actions. Remember that in the middle of all that AI magic, Flow is still your trusty friend. I’ve had head scratchers solved by the information in a handy Flow error email. All of those skills you have debugging Flow will come to your aid when trying to make your agent as successful as possible.

At the end of the day, your agent is another user on the platform. Treat it like you would any other user in terms of security and access. If you’ve ever set up an integration user to handle an external system, the concept is the same when thinking in terms of field-level security. If the agent is acting strange, think of it like a user to see if something that would be wrong with a normal user comes to mind.

Tip 6: Have fun with your loading text

Your mileage will vary as to how much fun you’ll be allowed to put into text your users will see while the agent is working. Our internal agent has several that are references to common sci-fi movies and shows. If you don’t think your stakeholders will approve something like that, consider at least something unique. I started this just to add some whimsy to the AI, but what I found is that it can be a very handy indicator that a custom action is being used, and possibly which one.

Bonus: Tip 7: Did you try turning it on and off?

This is a common problem I’ve run into with my testing that doesn’t neatly fit into the other tips. When tinkering with Agent Builder, you might be changing things while others are already in a session. When you reactivate the agent (and right, remember to reactivate the agent), if people are still having trouble, have them clear the chat history. This should give them a fresh session.

Continue learning and sharing

AI is one of the fastest-moving technologies ever produced—and it isn’t showing any signs of slowing down. Enhancements and updates to Agentforce are happening rapidly, so follow us here to keep learning. Join the Agentforce Trailblazer Community to ask and answer questions from your fellow Trailblazers, and attend local community events to share your experiences.