Agent Script Reference: Variables

Variables let agents deterministically remember information across conversation turns, track progress, and maintain context throughout the session. You define all variables in the variables block, and all topics in the agent can access the variables.

There are several types of variables:

regular variable: You can initialize a variable with a default value, and the agent can change the variable's value.
linked variable: The value of a linked variable is tied to an output such as an action's output. Linked variables can't have a default value.
system variable: Predefined, prepopulated system variables that you can use in your agent.

Variable names must follow Salesforce developer name standards:

Begin with a letter, not an underscore.
Contain only alphanumeric characters and underscores.
Can't end with underscore.
Can't contain consecutive underscores (__).
Maximum length of 80 characters.

To reference a variable from the script, use @variables.<variable_name>. To reference a variable from within reasoning instructions, use {!@variables.<variable_name>}.

Regular variables have these properties:

mutable - Optional. Allows the agent to change the variable's value. To ensure a variable's value is never changed, define the variable without mutable.
description - describes the variable. Optional. If you want the LLM to use reasoning to set the variable's value, include a description. See Let the LLM set variables with user-entered information (slot filling).
label - Optional. The variable's name as displayed in the UI. By default, the description is generated from the name. For example, if your variable's name is my_var, the UI displays the label My Var.

Regular variables can have these types:

Type	Notes	Example
`string`	Any alphanumeric string without special characters.	`name: mutable string = "John Doe2"`
`number`	Use for both integers and decimals. For example, 42 or 3.14. Compiles to IEEE 754 double-precision floating point.	`age: mutable number = 25`, `price: mutable number = 99.99`
`boolean`	Allowed values are `True` or `False`. The value is case-sensitive, so capitalize the first letter.	`is_active: mutable boolean = True`
`object`	Value is a complex JSON object in the form `{"key": "value"}.`	`order_line: mutable object = {"SKU": "abc12344409","count": 42}`
`date`	Any valid date format.	`start_date: mutable date = 2025-01-15`
`id`	A Salesforce record ID.	`"0015000000XyZ12"`
`list [type]`	A list of values of the specified type. All primitive types are supported.	`flags: mutable list[boolean] = [True, False, True]`, `scores: list[number] = [95, 87.5, 92]`

A linked variable's value is tied to a source, such as an action's output. Linked variables have these restrictions:

can't have a default value
can't be set by the agent
can't be an object or a list

Linked variables can have these types:

string
number
boolean
date
id

Agent Script provides predefined, prepopulated system variables that you can use in your agent. To access system variables, use @system_variables.<variable_name>. A system variable is:

read-only, so you can't change its value
predefined, so you don't define it in the variables block
used in the same places as a regular variable or a linked variable

Currently, @system_variables.user_input is the only system variable.

The user_input system variable contains the customer's most recent utterance (not the entire conversation history).

The LLM remembers the entire conversation history, so you don't typically need to use @system_variables.user_input unless you're passing the last thing a customer said into an action.

In this example, we pass the last customer utterance into a sentiment analysis action. Although the agent's LLM can also analyze sentiment, we want to use a prompt template action that understands industry-specific terminology and our customer's rapidly-changing language patterns.

For examples and patterns using variables, see Agent Script Pattern: Using Variables Effectively.