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.

Why Use This Pattern

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.

Reasoning Transitions

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

Transitions in Reasoning Actions

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

1start_agent agent_router:
2  description: "Welcome the user and determine the appropriate subagent"
3
4  reasoning:
5    instructions: ->
6      | Welcome the user and analyze their input to determine
7        the most appropriate subagent to handle their request.
8
9    actions:
10      go_to_order: @utils.transition to @subagent.Order_Management
11        description: "Handles order lookup, refunds, order updates."
12
13      go_to_faq: @utils.transition to @subagent.General_FAQ
14        description: "Handles FAQ lookup and common questions."
15
16      go_to_escalation: @utils.transition to @subagent.Escalation
17        description: "Escalate to a human representative."

Filtered Transitions

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

1reasoning:
2  actions:
3    go_to_identity: @utils.transition to @subagent.Identity
4      description: "Verifies user identity"
5      available when @variables.verified == False
6
7    go_to_order: @utils.transition to @subagent.Order_Management
8      description: "Handles order management"
9      available when @variables.verified == True

See the Filtering Pattern.

Transitions in Instructions

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

1reasoning:
2  instructions: ->
3    | If the user asks for a service agent or seems upset,
4      go to {!@actions.go_to_escalation}.
5
6  actions:
7    go_to_escalation: @utils.transition to @subagent.Escalation
8      description: "Escalate if requested or needed."

Deterministic Transitions

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.

Note

Conditional Transitions in Reasoning Instructions

Deterministically route users based on state or business rules.

1reasoning:
2  instructions: ->
3    if @variables.loyalty_tier == "Platinum VIP":
4      transition to @subagent.vip_support

The transition happens before the LLM processes any other instructions.

Transition After Action

Chain a transition after an action completes.

1reasoning:
2  instructions: ->
3    | Call {!@actions.validate_user_ready} to check if the user is ready.
4
5  actions:
6    validate_user_ready: @actions.validate_user_ready
7      with user_id=@variables.user_id
8      transition to @subagent.analyze_issue

Tips

Reasoning Transition Tips

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.

Deterministic Transition Tips

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.