Agent Script Pattern: Topic Transitions

Move execution from one topic to another using the @utils.transition to command.

Transitions move execution from one topic to another. You can expose them as reasoning actions (sometimes described as tools in the developer guide) for the LLM to select, execute them deterministically with conditionals, or chain them after actions complete.

Transitions route users to specialized topics based on their needs. They're one way—when a transition occurs, Agentforce discards any prompt from the current topic and processes the new topic instead.

Pattern Examples: When a user asks about a refund, transition them from the General FAQ topic to the specialized Returns topic. Or, after validating a user's identity, automatically transition to the Order Management topic to continue the conversation.

The following transitions can occur based on the LLM's reasoning. Deterministic transitions are described in the next section.

Expose transitions as reasoning actions (tools) that the LLM can choose to use.

Combine transitions with available when to control which topics are accessible.

See the Filtering Pattern.

When exposing transitions as reasoning actions (tools), reference them in your prompt so the LLM knows when to use them.

The following transitions occur deterministically based on your instructions. Reasoning transitions are described in the previous section.

Transitions in reasoning instructions don’t use the @utils. prefix.

Deterministically route users based on state or business rules.

The transition happens before the LLM processes any other instructions.

Chain a transition after an action completes.

  • Use descriptive topic names: Names should clearly indicate the topic's purpose.
  • Provide clear descriptions: Help the LLM understand when to use each transition.
  • Use the go_to_ prefix: Name transition actions with a go_to_ prefix (for example, go_to_orders) so the agent understands they navigate to other topics.
  • Reference transitions in prompt: When exposing transitions as reasoning actions, you can reference them in your prompt (for example, {!@actions.go_to_escalation}) so the LLM knows when to use them.
  • Use deterministic transitions sparingly: Only when you need guaranteed routing; otherwise let the LLM choose.
  • Place transitions first: When using conditional transitions, put them at the top of instructions so they execute before any other instructions. If the agent transitions to another topic before reasoning, no prompt is sent to the LLM. Prior instructions aren't used or preserved, so executing them just increases latency and (in the case of running an action) can incur costs.
  • Avoid transition loops: Ensure your topic flow doesn't create infinite loops. For example, you don't want to introduce some logic that causes a transition from topic A to topic B but also causes a transition from topic B back to A, and then repeat.