Agent Script Pattern: Using Variables Effectively

Variables store information about the agent's current state across topics and turns.

Variables help you track state that affects agent behavior, pass data among topics, 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 topics, 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, topics, and prompts are available.

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

Initialize variables with sensible defaults so conditional checks work correctly.

Clear descriptions help the agent use variables correctly.

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.

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

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.

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).
  • 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.