Agent Script Pattern: Subagent Transitions

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

Transitions move execution from one subagent 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 subagents based on their needs. They're one way—when a transition occurs, Agentforce discards any prompt from the current subagent and processes the new subagent instead.

Pattern Examples: When a user asks about a refund, transition them from the General FAQ subagent to the specialized Returns subagent. Or, after validating a user's identity, automatically transition to the Order Management subagent 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 subagents 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 subagent names: Names should clearly indicate the subagent'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 subagents.
  • 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 subagent 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 subagent flow doesn't create infinite loops. For example, you don't want to introduce some logic that causes a transition from subagent A to subagent B but also causes a transition from subagent B back to A, and then repeat.