Troubleshooting Agents

My agent is choosing the wrong subagent for the user question or request.

To select a subagent, an agent looks at the last six turns of the conversation history, including the user’s most recent message. The agent compares these with names and classification descriptions of the subagents assigned to the agent and selects the best match.

When you expect user utterances to trigger a certain subagent and your agent misclassifies them, check the name and classification description for the subagent. Effective subagent names describe what the subagent does in natural language. Effective classification descriptions clearly describe what the subagent does and identify the types of user requests that must be classified into the subagent. Consider adding key terms, examples, or example user requests.

Make sure that you have no more than 10 actions in your subagent and no more than 10 subagents assigned to your agent. If there are too many actions and subagents, the agent can choose an incorrect one.

My agent is using the wrong action for the user question or request.

Agents use action instructions and subagent instructions to select an action, so plan to troubleshoot on both levels.

• Verify that your agent is choosing the right subagent and selecting the wrong action within the subagent in Agentforce Builder plan canvas, and not choosing the wrong subagent altogether.
• Test and iterate on your agent action names and instructions in Agentforce Builder, including input and output instructions. Effective names and instructions for agent actions, inputs, and outputs describe what the action does in natural language. For example, the action name “lookup_products” is more effective than “action_agent_searchForRecords_products_only.” Learn more about best practices for writing action instructions.
• Add or modify subagent instructions to provide direct guidance about when to launch a specific action. Learn more about best practices for writing subagent instructions.
• Verify that the action instructions and subagent instructions don’t conflict with each other. Contradicting instructions can cause errors and degrade agent performance.
• Make sure that you have no more than 10 actions in your subagent and no more than 10 subagents assigned to your agent. If there are too many actions and subagents, the agent can choose an incorrect one.

My agent output is incorrect or not what I expected.

If your agent action uses sources (for example, the Answer Questions with Knowledge action uses your knowledge base), verify the output of your action against the content of your sources. Before making any changes to an agent action or subagent, consider altering the source content or limiting the sources that your action searches. This is particularly effective if the issue affects only one or a few of the sources in your database.

Test and iterate on the instructions for the related subagent, action, and associated inputs and outputs. Make sure to verify the behavior of the reference action itself. This involves testing the Apex class, flow, or prompt template your action is built on for any issues.

To improve agent outputs at the action level, you can add an instruction to ensure inputs to your actions reflect your desired output. For example, if you want your agent to include a model number in a search query, you can add a subagent instruction to ask the user for a model number. Then modify the action instructions, including the input instructions, to require the model number in the query. You can also use instructions to provide context for the agent, such as defining business-specific acronyms or explaining processes.

My agent isn’t selecting the right inputs to pass into the action.

Add more details to the action input instructions. Input instructions help an agent understand the context of a conversation and what data to use. Effective input instructions can include the data type of the required information, specific fields or values, how the information must be retrieved, and any special rules about how you expect the action to be used. Learn more about best practices for writing action input instructions.

My agent isn’t consistently following the rules I provide.

Agents are powered by a large language model (LLM). LLMs are nondeterministic, so there’s always some variation in responses. However, following best practices for subagent and action fields can help agents stay on track.

• Be as specific, clear, and direct as possible. Provide contextual details about your use case so your agent is more likely to return a consistent response. More detail is often better than less. For example, it can be helpful to define business-specific acronyms or explain processes.
• Provide examples that help your agent find patterns for how to respond to common, repeated scenarios.
• Carefully iterate on and test your subagents and actions. Defining effective instructions and other fields is an iterative process.
• Verify that the action instructions and subagent instructions don’t conflict with each other. Contradicting instructions can cause errors and degrade agent performance.
• Don’t include sensitive or deterministic business rules (for example, “Don’t refund an order unless it was within 30 business days.”) in subagent or action instructions. For consistent performance, build these requirements into the functionality of the reference action (for example, the Apex class or flow that an agent action references).

Agents don’t follow subagent instructions in the order they appear. If you want your agent to follow steps in a specific order, put the steps in one instruction field and use clear order words, such as “First, do X... Second, do Y... Finally, do Z…” Limit the instructions to a few simple steps. If your sequential instruction is too complex, the agent can follow the steps inconsistently or out of sequence.

If your agent tries to do something that it shouldn't (for example, issuing refunds when it should only handle returns), use the subagent scope instead of subagent instructions. After an agent has selected a subagent based on user input, the scope gives an agent more information about what it’s able to do with a subagent. Describe what the agent can do with the subagent as well as what it shouldn’t do (for example, “You aren’t able to make new reservations.”).

If you’ve followed all of these best practices and your agent is still behaving unreliably, you may have too many instructions. Reducing the number and complexity of instructions can help your agent reach consistent baseline functionality. Start by paring down your instructions to the fewest instructions necessary for your agent to handle your basic use cases. Then add instructions one by one to capture edge cases.

My agent is having a hard time understanding user messages.

Because agents accept free-text input, sometimes user input can be vague or otherwise difficult for the agent to classify. You can add instructions to one or more of your subagents to direct your agent to clarify what the user is requesting or asking about. For example, “If the user’s message is unclear, always ask clarifying questions to get more information from the user.”

My agent isn’t consistently updating the page context when updating fields or switching between records.

If a supported action is triggered by a user’s request, Agentforce (Default) is aware of which page the user is on. Sometimes the agent maintains the previous page’s context during a conversation.

If your use case requires an agent to always update the page context, you can add instructions to a subagent. For example, “Always generate a new summary by calling SummarizeRecord when asked for a record summary. Do not respond with any summary from the chat history.”

You can also use conversation variables. For example, assign the currentRecordId variable to the recordId action input on the Summarize Record action. For more information about variables, see Agent Variables.

To troubleshoot, users can also adjust their requests to be more specific. For example, they can ask the agent, “summarize this record with the latest information.”