Resolve Routing, Action, and Prompting Issues

Learning Objectives

After completing this unit, you’ll be able to:

Diagnose why a subagent or action isn’t invoked as expected.
Configure context variables using deterministic mechanisms.
Apply prompting best practices to reduce unpredictable behavior.

Resolve Routing Issues

Every agent comes with a special subagent called Agent Router. It is defined as the starting subagent for every agent conversation, and it’s a good place to start when looking for routing issues.

By default, the agent uses Agent Router to classify all the other subagents. Classification is the process of selecting the most relevant subagent based on what the user wants to do and the jobs that the agent can do. Transitions are set in the Agent Router’s reasoning actions, to make them available in the agent conversation. The agent compares the recent conversation history, including the user’s most recent message, to the names and descriptions of all of the subagents in the Agent Router’s reasoning actions to select the best match.

You can edit the Agent Router just like any other subagent, so you can customize its reasoning instructions and actions to set initial variables and add logic to control your subagent classification and routing.

Add conditions, actions, and variables to drive classification to particular subagents.
Exclude a subagent from classification based on filters (Make this action available when:).
Remove references to a subagent if you want the subagent to be accessible only via transitions from other subagents.

You can use filters and variables to control access and routing to subagents. For example, you can add filters based on a variable to ensure that certain subagents are available only to verified customers. Look at the following example.

List of subagents showing the verified variable set to True for Order Management, General FAQ, and Escalation subagents.

In this example, conversations are routed based on the verified variable in reasoning actions. The Order Management, General FAQ, and Escalation subagents are available only when the customer is verified (verified equals True). If the customer isn’t verified (verified equals False), the conversation is routed to the Identify Verification subagent.

Make Your Context Explicit

Agents are like someone new on the team. They don’t have all the backstory of why things are the way they are and why things work like they should. You have to be very specific with the instructions, descriptions, and directions that you give to the agent and its actions.

Context in Configuration and Data

Raw field values mean nothing without explanation. When you map data to pass to an agent, never assume the value speaks for itself.

A raw merge field like {!Account.Id} tells the reasoning engine nothing about what the value means or when it might be blank. Rewrite it with a label: Account record Id ({!Account.Id}). Apply that same thinking to every prompt template and instruction you write. Ask yourself:

Did you give the agent a role to play?
Did you explain the context around each field, not just the field itself?
Did you account for cases where a related field, object, or list might be empty?

Context Variables

Context variables need extra care. Don’t assume the agent infers them from prompt instructions; they aren’t automatically available in Agentforce Builder. Set context variables directly through action output mapping, variable mapping in configuration, or flow and structured assignment logic.

Any logic that depends on a context variable needs that variable initialized before evaluation. Skip this step, and the agent might behave unpredictably or skip a subagent or action altogether.

Make sure any context variables your routing, filters, or actions depend on actually exist and are populated before the agent evaluates them. Review your configuration to confirm variables are set at the right point in the agent’s execution.

Diagnose a Missing Subagent or Action

If an agent skips the subagent or action you expect, check these common causes.

Prompting issues in the subagent or action description.
Subagent or action filters that exclude it.
Missing context variables.
Permission restrictions.

Start with subagent and action filters. Confirm they're configured correctly. Make sure any context variables they depend on exist before evaluation.

Write Prompts the Agent Can Follow

Prompting issues are the most frequent cause of unexpected Agentforce behavior. Unlike deterministic bots, LLM-based agents can behave unpredictably when prompts are unclear.

Use these prompting best practices.

Draw boundaries. Make subagent and instruction boundaries distinct. Every subagent should map to a specific role or task. Make sure each subagent’s purpose and scope are explicit and nonoverlapping. If two subagents have similar-sounding instructions, the agent will guess, leading to errors.
Be explicit and clear. Use unambiguous language in subagent and action descriptions, and make sure instructions do not conflict. Resolve pronoun and term ambiguity. Words like “mine” or “my” are common sources of confusion. Does “my accounts” mean records the user owns, or records where the user is a related contact? Don't leave that to the agent to guess.
Avoid inference. Don’t rely on the LLM to infer business rules; state them directly.
Define scope. Clearly define when an action should and shouldn’t run.
Clarify outputs. Structure and describe action outputs clearly. Specify the tone, brevity, and the format you want the response in.

Tightening your descriptions and instructions resolves a surprising number of “the agent isn’t doing what I told it to do” issues.

The Limits of Prompting

If all your instruction-tweaking fails to produce the desired result, consider adding programmatic logic to your instructions to guarantee more consistent outcomes. The beauty of Agent Script is that it offers hybrid reasoning, so you get the best of both worlds: the predictability of programmatic logic combined with the reasoning power of LLMs.

예상 시간

주제

도움말 검색

Agentforce 자원