Troubleshooting Agentforce Responses

This guide is a dedicated resource for diagnosing and solving common issues you may encounter with Agentforce user prompts. Topics are where you will do most of your troubleshooting, so this guide will be focused there.

Common Scenarios for Using This Guide

This article is for you if you are a Salesforce Administrator who needs to:

• Set up Agentforce for the first time in your production environment.
• Install and test Agentforce in a Salesforce sandbox

Fixing Common Problems

• Problem: An industry-specific Topic has disappeared.

  • Solution: If a user removes one of the custom topics from the agent, it gets deleted permanently from the Salesforce org. The only way to restore the topic is to reinstall the package.

  To prevent the deletion of topics you later need, the best practice is to create a new agent for testing rather than removing topics from the default agent.

How to Test and Debug Agent Responses

The primary tool for validating user prompts and diagnosing why an agent is not responding as expected is the Agentbuilder.

Step 1: Open Agentbuilder

1. Navigate to Setup.

2. In the Quick Find box, type "agent".

3. Under Agentforce Studio, click on Agentforce Agents.

4. Click on the caret next to the name of the agent you want to test (EX: Amplify Screener (Default) Version 1).

5. Click the active version (EX: Version 1). This will open a new tab.

Step 2: Test the Prompt in the Conversation Preview

Once in Agentbuilder, you can use the Conversation Preview window on the right to type in user prompts and check the response. The middle section of the screen will show you which Topic and Actions the agent selected to generate the response, helping you identify any errors in its reasoning.

Performing Context-Specific Testing

For more accurate testing, you can simulate applying certain conditions. For example, this allows you to test how the agent behaves when a user is on a specific page, such as a record page within the Talent Rover app.

1. In the Conversation Preview section, click the eye icon to open the Edit Preview Conditions window.
2. Specify the context for your test by selecting the parameter you want associated with the text (EX: App, Page Type, specific Record, etc).
3. Click Apply.
4. In the Conversation Preview, enter your prompt in the Describe your task or ask a question... field and press Enter.

Use the data displayed in the center pane to guide your instruction refinements.

If you want to make changes to Agentforce, you will have to Deactivate the Agent first.

Best Practices for Improving Agentforce Responses

If Agentforce doesn’t give the answer you were expecting, use these tips to get better results.

Keep the Classification Descriptions Customer-Focused

Classification Descriptions act as the “label” Agentforce uses to decide when and how to respond. Writing them in plain, user-focused language ensures the bot understands the intent and surfaces the right Topic at the right time.

• Write descriptions as if you’re explaining the purpose to an end-user.

Example: “This Topic guides users through editing field mappings in ATS.”

• Clear descriptions make it easier for Agentforce (and your team) to surface the right response.

Start with a Clear Topic Scope

A clear scope keeps Agentforce from drifting into unrelated topics. To help Agentforce in this task, define exactly what the topic should cover.

"Your job is to a pull order statuses for users."

If you find intent for a prompt routes to an incorrect topic, you can add guardrails in that Topic Scope to indicate those items are Out of Scope.

Agentforce displays the least amount of confusion when 8-13 topics are used.

Write Explicit in Instructions

Agentforce performs best when directions are unambiguous. By giving it step-by-step instructions with no room for interpretation, you remove guesswork and keep responses aligned with your intent.

• Spell out exactly what you want Agentforce to do at each step.

• Agentforce is trained to recognize human phrasing, not abstract shorthand. Writing instructions in plain, conversational language ensures the bot responds in a way that feels natural to users while staying on task.

"When the user enters their first query, give a friendly greeting using the user's First Name."

• Avoid vague phrases like “capture feedback”; instead, write “Prompt the customer for optional feedback.”

  • This prevents Agentforce from interpreting your intent incorrectly.

• If the agent isn't directing your users properly, you may need to explicitly add to the output you want to display to the user in the instruction.

  "If no record is returned, always ask the user for their ID. - Example: 'Can you please confirm your ID for me so that I may present you with the record you are looking for?' "

Use Raw Code Format for Complex Prompts

Some workflows go beyond simple text prompts. When instructions require conditional logic, chaining, or variable checks, raw code provides the precision and control needed to guide Agentforce reliably.

• Add raw code (JSON, conditional logic, variable validation) when instructions become more complex or need to be chained.
• Document each step so the intent is clear to future editors.

### PRODUCT RETURN FLOW

- Ask for the order number.  
- If valid, run `Generate Return Label` and provide a link.  
- If invalid, allow two retries, then fallback to “Contact Support.”  
- Always confirm back: “Your return label is ready.”  

Ground Actions in Parameters

Actions only work as intended when the right inputs are provided. By grounding Actions in clearly defined parameters, you prevent execution errors and help Agentforce deliver consistent outcomes.

• Call Actions only when parameters (aka inputs) can be passed to the action.

These parameters can be passed as Variables in the Action or in the Instructions, but they must be explicitly stated to avoid Agentforce confusion (current or down the line).

• Plan for Fallbacks for if a variable is missing or an Action fails. Agentforce should respond with guidance. Not filling this in could allow for intent misroutes. Always specify what should happen if an Action fails (i.e. retry, ask for missing info, or fallback).

  "If no contact is present, prompt the user for it and then retry the Action.”

  Fallbacks can also come in handy when other instructions aren't behaving as anticpated.

Iterate and Monitor

Agentforce is not a “set it and forget it” system. Continuous monitoring and small refinements turn every interaction into training data, improving Topic accuracy and reducing misroutes over time.

• Review how Topics perform after launch. Look for repeated escalations, dead ends, or misfires.
• Use logs to spot where Agentforce misunderstood instructions and adjust wording or scope.
  • To view logs go to Agentforce Builder > Events tab.
• Small refinements make Topics more accurate over time.