Agentforce uses an AI reasoning engine to generate responses and decide how to handle requests. So when your agent does something unexpected, the instinctive fix—“add another instruction telling it not to do that”—isn’t always the right approach.
Instructions are just one of several controls you can use to influence agent behavior. Depending on the issue, the right fix may involve subagent selection, actions, grounding, variables, configuration, or deterministic logic. Choosing the right control is important; otherwise, you can end up repeatedly rewriting instructions without addressing the underlying cause of the behavior.
This guide helps you:
These checks help establish whether you’re dealing with a repeatable configuration issue, normal model variability, or an execution/runtime issue.
If the issue remains, use Step 2 to locate where the behavior went wrong before changing instructions.
Before troubleshooting, it helps to know your full toolkit—not every issue is an instructions problem.
| # | Control | What it does | When to reach for it | Don’t use it for |
|---|---|---|---|---|
| 1 | Instruction-free subagent and prompt action selection | Allows the agent to select the appropriate subagent and prompt action without additional custom instructions | Simple, low-stakes choices where flexibility is acceptable | Business-critical behavior where a specific outcome must always occur |
| 2 | Instructions | Provides natural-language guidance to a subagent or action | Judgment calls, tone, preferences, and general behavioral guidance | Critical validation, sensitive business rules, behavior that must happen the same way every time, or fixing subagent/topic routing problems (instructions don’t affect selection — see Step 3) |
| 3 | Data grounding | Provides information from Knowledge, Data Cloud, or other sources that the agent can use to answer a request | When the agent needs accurate, supported facts or records | Decisions that don’t depend on retrieving specific information |
| 4 | Variables | Passes data explicitly through context or action outputs instead of relying on the model to infer values from conversation text | Values that must reliably control filters, actions, or subsequent steps | Simple conversational guidance that belongs in instructions |
| 5 | Deterministic Actions | Uses Apex, APIs, or Flow to perform defined operations | Business-critical logic, validation, calculations, integrations, or processes that must execute reliably | Simple conversational guidance where some variation is acceptable |
| 6 | Agent Script | Provides deterministic authoring, including ordered logic, conditional behavior, and controlled transitions | When you need deterministic behavior around transitions, reasoning steps, or business rules | Problems that can be reliably handled by simpler controls above |
Practical rule of thumb: If you’ve repeatedly rewritten the same instruction and the behavior remains inconsistent, consider whether the problem actually needs a different control—such as grounding, variables, a deterministic action, or Agent Script.
This is particularly important for business-critical behavior. If something must happen the same way every time, don’t rely solely on natural-language instructions to enforce it.
This framework aligns with Salesforce’s six levels of agentic control and the Agentforce reasoning engine. At a high level, the engine classifies the request, resolves the relevant context and instructions, reasons about what to do, executes actions when needed, observes the results, and can repeat the reasoning/action cycle before producing a final response. Before the final response is sent, a grounding check verifies that the response is based on information from actions or instructions, follows the relevant subagent instructions, and stays within the subagent scope.
See Understanding the Atlas Reasoning Engine Workflow for more detail.
Note: Salesforce documentation now uses Subagent in place of Topic and Agent Router in place of Topic Selector. During the transition, you may see a mix of the old and new terms in Salesforce documentation and UI. The underlying functionality is unchanged.
Before changing anything, determine where in the execution path the problem occurs.
A useful troubleshooting sequence is:
This prevents you from immediately changing instructions when the actual problem is routing, action behavior, data retrieval, or configuration.
| What you observe | What it suggests | What to do |
|---|---|---|
| Fails the same way every time | A repeatable configuration, data, action, setup, or runtime issue | Locate the failing layer and address that layer directly |
| Sometimes succeeds and sometimes fails on similar requests | Ambiguous configuration/instructions or normal LLM variability | Inspect the relevant control and test multiple variations |
| Only fails for one specific input or phrasing | An edge case, missing data, or ambiguous instruction | Add a targeted rule or fix the underlying data/action |
| Wording changes but the outcome remains correct | Normal variation in generated language | Focus on whether the required outcome is correct rather than identical wording |
If Agentforce Session Tracing is enabled for your org, use it to investigate the session instead of relying only on the conversation transcript. Session Tracing captures detailed session information, including interactions, reasoning-engine executions, actions, prompt and gateway inputs/outputs, errors, and final responses. The Session Tracing Data Model can also be queried to investigate variables, action failures, execution patterns, and performance.
See Troubleshoot Agentforce Agent Behavior Using Session Telemetry and Agentforce Session Tracing for setup and usage details.
Testing in Agent Builder?
Use Plan Tracer to inspect the agent’s execution plan, including subagent selection, action selection, and the reasoning path used during the test.
| What you’re seeing | What’s likely happening | Where to check | What to change |
|---|---|---|---|
| Agent is slow, inconsistent, or appears to make unsupported decisions | Instructions may be overly long, complex, or ambiguous | Review the subagent and action instructions | Make instructions concise, direct, and specific. Remove unnecessary context and contradictory rules |
| Wrong subagent is selected | Subagent classification descriptions may overlap or be too vague — subagent instructions and scope have no effect on selection; only the name and classification description do | Compare classification descriptions and names across subagents | Rewrite the classification description to be specific and distinct. Do not edit the subagent’s instructions or scope to try to fix this |
| Wrong action is selected within a subagent | Action descriptions may have overlapping or unclear boundaries | Compare action names and descriptions | Make each action description specific and clearly distinguish what belongs—and does not belong—to that action |
| Agent becomes harder to manage as more subagents/actions are added | More choices can make routing and action selection harder | Review the number of subagents and actions assigned to the affected subagent | Salesforce recommends limiting an agent to roughly 10–15 subagents and assigning no more than 15 actions to a subagent to help reduce inconsistency and improve performance |
| Multi-step process happens out of order or a step is skipped | The sequence is being expressed as natural-language instructions rather than deterministic logic | Review whether the sequence is business-critical | For critical sequences, move the logic into Flow, Apex, API-based actions, or Agent Script |
| Action receives the wrong, missing, or malformed input | The input may not be clearly defined, validated, or mapped | Check the action input configuration, instructions, mappings, and underlying action logic | Define the input’s purpose and format clearly. Prefer validation and formatting in deterministic logic and use variable mapping when the value can be passed deterministically |
| Agent escalates unexpectedly or repeats an action | The action may be failing, instructions may trigger escalation, or the agent may be unable to complete the user’s intent | Review action execution, errors, escalation instructions, and the execution trace | Fix the underlying action failure, refine escalation behavior, or simplify the execution path |
Critical distinction: A subagent’s routing/selection is driven only by its name and classification description — never by its scope or its instructions. Both of those are only read after a subagent has already been selected.
If the wrong subagent is being selected, editing that subagent’s scope or instructions will not fix it — rewrite the classification description instead, making sure it’s phrased in natural language, distinctly covers the trigger phrases you expect, and doesn’t overlap with other subagents’ descriptions.
Before the final response is delivered, Agentforce performs a grounding check to help verify that the response is based on accurate information from actions or instructions, follows the relevant subagent instructions, and stays within the subagent’s scope.
This can sometimes result in a response being revised before it is shown to the user.
| What you’re seeing | What’s likely happening | Where to check | What to change |
|---|---|---|---|
| Agent gives an answer and then visibly retracts or rewrites it | The generated response may not have satisfied the grounding check | Review the subagent scope, instructions, and data/action outputs | Narrow the scope and ensure the response is based on the correct data or action output |
| Conversations feel slower, especially when responses are long | Additional context, action execution, and response validation can increase processing time | Review the amount of context and data being passed to the agent | Reduce unnecessary context, narrow scope, and avoid returning large amounts of unnecessary data |
| Answer is incorrect or unsupported even though the agent used Knowledge | Retrieved information may be incomplete, incorrect, or not the information needed for the request | Review Knowledge retrieval, grounding configuration, and returned content | Improve the source content, retrieval configuration, or grounding strategy |
| No citations are shown even though Knowledge was used | Citation behavior depends on the relevant Knowledge/action configuration and response path | Review the Knowledge/action citation configuration | Enable citations where supported and appropriate |
| Response or generated content is cut off | The response or action output may have exceeded an applicable limit | Check the size of the generated response and action output | Avoid unnecessarily large outputs and return only the information the agent needs |
| A fixed message is altered or isn’t delivered as expected | The message may be generated by the agent rather than delivered deterministically | Check how the message is generated | For content that must remain exact, consider delivering it through a deterministic mechanism such as Flow or Agent Script |
| What you’re seeing | What’s likely happening | Where to check | What to change |
|---|---|---|---|
| Agent is completely unresponsive or repeatedly shows an error such as “Something went wrong, refresh the conversation” | Agentforce may not be fully activated or the required configuration may be missing | Review the relevant Agentforce activation/configuration and confirm the required agent exists | Correct the activation/configuration and retest |
| Subagent or action is unavailable even though it should apply | A filter may exclude it, or the running user/service user may lack permission | Check filter conditions and relevant permission assignments | Correct the filter or work with your org administrator to provide the required permissions |
| Feature works live but not in Agent Builder, or vice versa | The testing environment may not have the same conversation context or variable values | Check whether filters depend on context variables | Provide appropriate test/default values when testing |
| Subagent/action is selected correctly only sometimes | A filter variable may be populated through nondeterministic instructions rather than deterministic mapping | Check how the variable is populated | Map the variable directly from an action output or another deterministic source |
| A Flow interview fails during agent execution | The Agentforce service user or running context may be missing required permissions, or the Flow itself may have an error | Review Flow errors, permissions, and the running context | Fix the Flow or provide the required permissions according to your Salesforce configuration |
| Escalations are routed somewhere unexpected | Escalation, fallback, channel, or routing configuration may not match the intended behavior | Review escalation configuration and channel/routing setup | Correct the relevant escalation or routing configuration |
| Agent responds in the wrong language | Agent language, locale, channel, or instruction language may not align | Review the agent language configuration, locale, channel/session settings, and language used in instructions | Correct the relevant language/locale configuration and keep instructions language-consistent |
| Links are missing from responses | A URL may be filtered, unavailable to the response path, or restricted by security configuration | Review the relevant URL/trusted URL configuration and the action that produces the link | Correct the applicable URL/security configuration where supported |
Don’t make a change and assume it worked—and don’t rely on a single conversation to prove it.
Testing whether an action’s logic works and testing whether the agent chooses and uses the action correctly are different questions.
| What you’re testing | The question | Where to check |
|---|---|---|
| Action logic | Does the Flow/Apex/API actually do the right thing for known inputs? | Flow Debugger, Apex debug logs, or direct action testing |
| Agent behavior | Does the agent select the right subagent/action and follow the intended instructions? | Agent Builder testing/preview and Plan Tracer |
| Production behavior | Does the change work across varied real sessions? | Session Tracing, where available, and review across multiple sessions |
Contact Salesforce Support when:
A well-described case helps the issue reach the right team faster.
Where available, include:
005391239

We use three kinds of cookies on our websites: required, functional, and advertising. You can choose whether functional and advertising cookies apply. Click on the different cookie categories to find out more about each category and to change the default settings.
Privacy Statement
Required cookies are necessary for basic website functionality. Some examples include: session cookies needed to transmit the website, authentication cookies, and security cookies.
Functional cookies enhance functions, performance, and services on the website. Some examples include: cookies used to analyze site traffic, cookies used for market research, and cookies used to display advertising that is not directed to a particular individual.
Advertising cookies track activity across websites in order to understand a viewer’s interests, and direct them specific marketing. Some examples include: cookies used for remarketing, or interest-based advertising.