Agent Script Reference: Utils

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.

This 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.

When 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.

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.

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.

escalate is a reserved keyword and can't be used for subagent or action names.