Agent Script Pattern: Using Variables Effectively

Variables store information about the agent’s current state across subagents and turns.

Why Use This Pattern

Variables help you track state that affects agent behavior, pass data among subagents, use data in conditionals, and show specific information to users. Use them strategically to track important information, but avoid over-constraining your agent by storing every piece of data.

Use variables for:

Storing values for reuse: Data for conditionals, inputs to actions in other subagents, or to show to users.
Storing action outputs: Results from actions that you need in conditional or other deterministic workflows.
available when clauses: Conditions to determine which actions, subagents, and prompts are available.

1variables:
2  member_name: mutable string
3    description: "The name of the member for personalized greetings"
4  verified: mutable boolean = False
5    description: "Whether the user's identity has been verified"
6  order_summary: mutable string = ""
7    description: "Summary of the user's current order"

Pattern Example: Store the user’s verification status in a variable so all subagents can check whether the user is verified before showing sensitive information.

Initialize Variables

Initialize variables with sensible defaults so conditional checks work correctly.

1variables:
2  # Use empty string for text that is fetched later
3  order_summary: mutable string = ""
4
5  # Use False for flags that start negative
6  verified: mutable boolean = False
7
8  # Leave uninitialized for values that must be provided
9  member_email: mutable string

Good Variable Descriptions

Clear descriptions help the agent use variables correctly.

1variables:
2  is_business_hours: mutable boolean = False
3    description: "Whether it is business hours. Used to determine if the agent can escalate to a live representative."
4
5  loyalty_tier: mutable string
6    description: "The customer's loyalty tier (Standard, Gold, or Platinum VIP). Used for personalized greetings and feature access."

Store Action Outputs

Store action outputs in variables if you need to use them in conditional expressions, as required inputs to another action, or for other deterministic workflows.

1reasoning:
2  instructions: ->
3    run @actions.lookup_current_order
4      with member_email=@variables.member_email
5      set @variables.order_summary=@outputs.order_summary
6      set @variables.order_id=@outputs.order_id
7
8    | Show the user their order: {!@variables.order_summary}

Share Information Between Subagents

You can use variables to share information, or state, between subagents. For example, to share the current temperature between all subagents in an agent, run the Get_Current_Weather_Data action and store the value of the temperature output in the global temperature variable.

1reasoning:
2    instructions: ->
3        # always get the current weather data
4        run @actions.Get_Current_Weather_Data
5            with city=@variables.user_city
6            # set the variable "temperature" with the
7            # current temperature so that other subagent has that info
8            set @variables.temperature = @outputs.temperature_celsius

Let the LLM Set Variables with User-Entered Information (Slot Filling)

Use ... to indicate that the LLM should use reasoning to set a variable’s value. For example, the LLM can ask the user for their first and last name, then use the capture_user_info tool to set those values in the variables first_name and last_name. Using reasoning to set a variable’s value is called slot filling.

For simple workflows, the LLM can figure out which actions to call based on the action’s description and name. In this example, we explicitly reference {!@capture_user_info} in the instructions to be sure the LLM stores the user information.

1reasoning:
2    instructions: -> Ask the user for their full name. Then, use {!@actions.capture_user_info} to set the value of the user's first and last name.
3    actions:
4        capture_user_info: @utils.setVariables
5            with first_name = ...
6            with last_name = ...
7            description: "Set the user's name as variables"

You can use slot-filling for top-level action inputs (which are called by the LLM), but not for chained action inputs (because they’re run deterministically).

Note

Tips

Name variables clearly. Use descriptive names like order_return_eligible not flag1.
In reasoning instructions, assign variables to action inputs and outputs. When you run an action in reasoning instructions, you must manually set variables for the inputs and outputs because the action is run before any reasoning takes place.
In reasoning actions, use variables as action inputs sparingly. Actions are made available to the agent when the agent has all the relevant action inputs, so specifying variables for too many inputs can cause the agent to select actions inconsistently. When you don’t specify a variable as input, the agent can usually decide the best input. Specify variables as inputs only when necessary, based on testing.
Store action outputs in variables when applicable. If you need to use them in conditional expressions, as required inputs to another action, or for other deterministic workflows.