Loading
Slack製品の問い合わせ先はSalesforce Helpへ統合・変更されます続きを読む

Troubleshooting Unexpected Agentforce Behavior: A Self-Service Guide

公開日: Aug 20, 2026
説明

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:

  1. Start with a few quick checks that can resolve many issues in minutes.
  2. Identify where the problem is occurring from the observed behavior and execution path.
  3. Choose the right control to address the underlying cause.
  4. Confirm your change actually worked before moving on.
解決策

Step 1: Start with a few quick checks

These checks help establish whether you’re dealing with a repeatable configuration issue, normal model variability, or an execution/runtime issue.

  • Run the same input multiple times. Agentforce uses an LLM and its behavior can be probabilistic. Repeating the same input helps determine whether the behavior is consistent or intermittent.
  • Try a few different phrasings of the same request. A fix that works only for one exact wording may not address the underlying issue.
  • Reproduce the behavior in a minimal test configuration with as few custom subagents, actions, and instructions as possible. If the behavior still occurs, that points you away from your specific customization and toward a broader configuration, data, or runtime issue.
  • Check activation and permissions. Verify that the agent, relevant subagents, actions, and required permissions are configured correctly.
  • Use Plan Tracer when testing in Agent Builder. It can help you inspect the execution plan, including subagent selection and action selection.
  • Use Agentforce Session Tracing when available. Session Tracing provides structured telemetry that can help identify where a session behaved unexpectedly.
  • If you’ve already made a change, verify that it was actually applied. Confirm that the configuration was saved, published/activated as required, and that you’re testing the updated version.

If the issue remains, use Step 2 to locate where the behavior went wrong before changing instructions.

Step 2: Understand the controls available to you

Before troubleshooting, it helps to know your full toolkit—not every issue is an instructions problem.

#ControlWhat it doesWhen to reach for itDon’t use it for
1Instruction-free subagent and prompt action selectionAllows the agent to select the appropriate subagent and prompt action without additional custom instructionsSimple, low-stakes choices where flexibility is acceptableBusiness-critical behavior where a specific outcome must always occur
2InstructionsProvides natural-language guidance to a subagent or actionJudgment calls, tone, preferences, and general behavioral guidanceCritical 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)
3Data groundingProvides information from Knowledge, Data Cloud, or other sources that the agent can use to answer a requestWhen the agent needs accurate, supported facts or recordsDecisions that don’t depend on retrieving specific information
4VariablesPasses data explicitly through context or action outputs instead of relying on the model to infer values from conversation textValues that must reliably control filters, actions, or subsequent stepsSimple conversational guidance that belongs in instructions
5Deterministic ActionsUses Apex, APIs, or Flow to perform defined operationsBusiness-critical logic, validation, calculations, integrations, or processes that must execute reliablySimple conversational guidance where some variation is acceptable
6Agent ScriptProvides deterministic authoring, including ordered logic, conditional behavior, and controlled transitionsWhen you need deterministic behavior around transitions, reasoning steps, or business rulesProblems 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.

Step 3: Diagnose the problem

Before changing anything, determine where in the execution path the problem occurs.

A useful troubleshooting sequence is:

  1. Subagent selection
  2. Action selection and execution
  3. Data and Knowledge output
  4. Instructions and prompting
  5. Configuration and system constraints

This prevents you from immediately changing instructions when the actual problem is routing, action behavior, data retrieval, or configuration.

First, look at the pattern across multiple runs

What you observeWhat it suggestsWhat to do
Fails the same way every timeA repeatable configuration, data, action, setup, or runtime issueLocate the failing layer and address that layer directly
Sometimes succeeds and sometimes fails on similar requestsAmbiguous configuration/instructions or normal LLM variabilityInspect the relevant control and test multiple variations
Only fails for one specific input or phrasingAn edge case, missing data, or ambiguous instructionAdd a targeted rule or fix the underlying data/action
Wording changes but the outcome remains correctNormal variation in generated languageFocus on whether the required outcome is correct rather than identical wording

Use session tracing instead of guessing


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.

A. Agent behavior, instructions, and subagent/action selection

What you’re seeingWhat’s likely happeningWhere to checkWhat to change
Agent is slow, inconsistent, or appears to make unsupported decisionsInstructions may be overly long, complex, or ambiguousReview the subagent and action instructionsMake instructions concise, direct, and specific. Remove unnecessary context and contradictory rules
Wrong subagent is selectedSubagent classification descriptions may overlap or be too vague — subagent instructions and scope have no effect on selection; only the name and classification description doCompare classification descriptions and names across subagentsRewrite 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 subagentAction descriptions may have overlapping or unclear boundariesCompare action names and descriptionsMake 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 addedMore choices can make routing and action selection harderReview the number of subagents and actions assigned to the affected subagentSalesforce 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 skippedThe sequence is being expressed as natural-language instructions rather than deterministic logicReview whether the sequence is business-criticalFor critical sequences, move the logic into Flow, Apex, API-based actions, or Agent Script
Action receives the wrong, missing, or malformed inputThe input may not be clearly defined, validated, or mappedCheck the action input configuration, instructions, mappings, and underlying action logicDefine 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 actionThe action may be failing, instructions may trigger escalation, or the agent may be unable to complete the user’s intentReview action execution, errors, escalation instructions, and the execution traceFix 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.

B. Grounding, data, and response validation

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 seeingWhat’s likely happeningWhere to checkWhat to change
Agent gives an answer and then visibly retracts or rewrites itThe generated response may not have satisfied the grounding checkReview the subagent scope, instructions, and data/action outputsNarrow the scope and ensure the response is based on the correct data or action output
Conversations feel slower, especially when responses are longAdditional context, action execution, and response validation can increase processing timeReview the amount of context and data being passed to the agentReduce unnecessary context, narrow scope, and avoid returning large amounts of unnecessary data
Answer is incorrect or unsupported even though the agent used KnowledgeRetrieved information may be incomplete, incorrect, or not the information needed for the requestReview Knowledge retrieval, grounding configuration, and returned contentImprove the source content, retrieval configuration, or grounding strategy
No citations are shown even though Knowledge was usedCitation behavior depends on the relevant Knowledge/action configuration and response pathReview the Knowledge/action citation configurationEnable citations where supported and appropriate
Response or generated content is cut offThe response or action output may have exceeded an applicable limitCheck the size of the generated response and action outputAvoid unnecessarily large outputs and return only the information the agent needs
A fixed message is altered or isn’t delivered as expectedThe message may be generated by the agent rather than delivered deterministicallyCheck how the message is generatedFor content that must remain exact, consider delivering it through a deterministic mechanism such as Flow or Agent Script


C. Setup, permissions, and availability

What you’re seeingWhat’s likely happeningWhere to checkWhat 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 missingReview the relevant Agentforce activation/configuration and confirm the required agent existsCorrect the activation/configuration and retest
Subagent or action is unavailable even though it should applyA filter may exclude it, or the running user/service user may lack permissionCheck filter conditions and relevant permission assignmentsCorrect the filter or work with your org administrator to provide the required permissions
Feature works live but not in Agent Builder, or vice versaThe testing environment may not have the same conversation context or variable valuesCheck whether filters depend on context variablesProvide appropriate test/default values when testing
Subagent/action is selected correctly only sometimesA filter variable may be populated through nondeterministic instructions rather than deterministic mappingCheck how the variable is populatedMap the variable directly from an action output or another deterministic source
A Flow interview fails during agent executionThe Agentforce service user or running context may be missing required permissions, or the Flow itself may have an errorReview Flow errors, permissions, and the running contextFix the Flow or provide the required permissions according to your Salesforce configuration
Escalations are routed somewhere unexpectedEscalation, fallback, channel, or routing configuration may not match the intended behaviorReview escalation configuration and channel/routing setupCorrect the relevant escalation or routing configuration
Agent responds in the wrong languageAgent language, locale, channel, or instruction language may not alignReview the agent language configuration, locale, channel/session settings, and language used in instructionsCorrect the relevant language/locale configuration and keep instructions language-consistent
Links are missing from responsesA URL may be filtered, unavailable to the response path, or restricted by security configurationReview the relevant URL/trusted URL configuration and the action that produces the linkCorrect the applicable URL/security configuration where supported

Step 4: Validate the change before moving on

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 testingThe questionWhere to check
Action logicDoes the Flow/Apex/API actually do the right thing for known inputs?Flow Debugger, Apex debug logs, or direct action testing
Agent behaviorDoes the agent select the right subagent/action and follow the intended instructions?Agent Builder testing/preview and Plan Tracer
Production behaviorDoes the change work across varied real sessions?Session Tracing, where available, and review across multiple sessions

A practical validation pattern

  1. Record the baseline—capture what happened before the change using the original input.
  2. Make one targeted change at a time so you can identify which change affected the outcome.
  3. Re-run the original input plus 2–3 variations of the same request.
  4. Check neighboring behavior after changes to routing, scope, instructions, or filters.
  5. Validate both positive and negative cases—confirm the agent does the intended thing and does not incorrectly apply the change to unrelated requests.
  6. Keep the change only if it improves the intended behavior without introducing a regression.
  7. Record a short before/after note so the investigation can be understood if the behavior resurfaces later.

When to contact Support

Contact Salesforce Support when:

  • The agent is completely unresponsive and there is no indication that a conversation ever started.
  • You’ve worked through the relevant troubleshooting section, applied the appropriate fix, and confirmed through testing that the behavior remains unchanged.
  • The issue appears to be a platform/runtime problem rather than an issue with your configuration.

A well-described case helps the issue reach the right team faster.

Where available, include:

  • A concise description of what you expected vs. what actually happened
  • One or more representative user inputs, not just a paraphrase
  • Whether the issue is consistent or intermittent, and approximately how often it reproduces
  • Session ID(s) or relevant Session Tracing data
  • The subagent and action you believe were selected, if known
  • Relevant Plan Tracer output
  • What you already tried and the before/after result
  • Specific error text, permission errors, or truncation symptoms
  • The agent/configuration version or deployment time, if relevant
その他のリソース
ナレッジ記事番号

005391239

 
読み込み中
Salesforce Help | Article