Utils are utility functions that can be used as tools, for example transition to subagents, run actions, or instruct the LLM to set variable values based on a customer’s utterance.
Tells the agent to move to a different subagent. For examples and patterns, see the Transitions Pattern.
Transitions are one way. There’s no return of control to the calling subagent. transition to executes immediately when encountered. The execution of the current directive block is halted, and control is passed to the new subagent.
You can signal a hand off immediately after an action completes by including transition logic in the actions: block. However, this may not occur until all actions are run.
1# during reasoning
2
3reasoning:
4 actions:
5 go_to_identity: @utils.transition to @subagent.Identity
6 description: "verifies user identity"
7 available when @variables.verified == False
8 go_to_order: @utils.transition to @subagent.Order_Management
9 description: "Handles order lookup, refunds, order updates, and summarizes status, order date, current location, delivery address, items, and driver name."
10 available when @variables.verified == True
11 go_to_faq: @utils.transition to @subagent.General_FAQ
12 description: "Handles FAQ lookup and provides answers to common questions."
13 available when @variables.verified == TrueThis code sample provides multiple transitions for order management, user verification, and answering common questions. Because these particular transitions are specified from within the reasoning actions, they can be executed by the reasoning engine when applicable. See Tools (Reasoning Actions).
You can also transition to a subagent from your reasoning instructions using transition to. This sample transitions based on a variable state.
1if @variables.approval_required:
2 transition to @subagent.approval_workflowWhen the specified subagent has completed, the flow of control doesn’t return to the original subagent, so you must explicitly create a transition back to the original subagent if that’s what you want. When transitioning back to a subagent, the flow starts at the beginning of the subagent, not where it last left off.
1# in topic A, specify that the flow of control jumps to topic_b
2
3search_another: @utils.transition to @subagent.topic_b
4 description: "Search for another order"
5
6# in topic B, specify that the flow of control goes (back) to topic_a
7
8back_to_order: @utils.transition to @subagent.topic_a
9 description: "Return to order details"See Referencing a Subagent as a Tool.
Tells the agent to define a variable based on the natural language description. The … token instructs the LLM to set the value of the variable.
The description instructs the LLM on how to set the value of the variable.
1reasoning:
2 actions:
3 set_first_name_variable: @utils.setVariables
4 with first_name = ...
5 description: "Get the user's first name"Tells the agent to escalate to a human service rep. To use utils.escalate, you need an active Omni-Channel connection. This must be defined in a connection messaging block with outbound_route_type and outbound_route_name values. See Agent Script Connection Block and Transfer Conversations from an Agent with an Omni-Channel Flow. The escalate utility function can be used instead of an escalation subagent.
1subagent my_topic_name:
2 reasoning:
3 instructions:
4 | call the action {!@actions.escalate_to_human} if the user wants to speak with a human rep
5 actions:
6 escalate_to_human: @utils.escalate
7 description: "Call this when you need to escalate to a human rep"
8 available when @variables.in_business_hoursescalate is a reserved keyword and can’t be used for subagent or action names.
Note
Tells the agent to end the conversation immediately. Use utils.end_session when the agent should terminate the session, for example after completing a task or when a specific condition is met.
In this example, the LLM can choose to end the conversation, for example if the customer is making inappropriate utterances.
1reasoning:
2 instructions: ->
3 | Use your general knowledge to answer the user's questions.
4 | If the user asks about aliens, you MUST say "aliens don't exist!" and run {!@actions.end_conversation} and end the conversation immediately.
5 actions:
6 end_conversation: @utils.end_sessionIn this example, the agent router chooses to run the go_to_EndSession action when the customer says the don’t need any more help. The go_to_EndSession action transitions to the EndSession subagent, which runs the end_session util.
1variables:
2 start_agent agent_router:
3 label: "Agent Router"
4 description: "Welcome the user and determine the appropriate subagent based on user input"
5 model_config:
6 model: "model://sfdc_ai__DefaultEinsteinHyperClassifier"
7 reasoning:
8 instructions: ->
9 | Select the best tool to call based on conversation history and user's intent.
10 actions:
11 go_to_EndSession: @utils.transition to @subagent.EndSession
12 description: "End the session when the user says the conversation is over, or they don't need any more help."
13
14 subagent EndSession:
15 label: "End Session"
16 description: "End the session when the user says the conversation is over, or they don't need any more help."
17 reasoning:
18 instructions: ->
19 | End the conversation immediately.
20 actions:
21 end_conversation: @utils.end_session
22 description: "End the session when the user says the conversation is over, or they don't need any more help."
j