Agent Script Reference: Variables (Custom and Linked)

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 subagents in the agent can access the variables.

This page covers custom and linked variables. For predefined runtime variables, see Agent Script Reference: System Variables.

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

Define variables in the Variables block.

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

Custom 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 to help the LLM set the value correctly. 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.
  • visibility - Optional. Default value is Internal. Set visibility to External to allow an API to set the variable’s value, or to change the variable’s value when testing the agent in simulate mode.

Custom variables can have these types:

TypeNotesExample
stringAny alphanumeric string without special characters.name: mutable string = ""
numberUse for both integers and decimals. For example, 42 or 3.14. Compiles to IEEE 754 double-precision floating point.age: mutable number, price: mutable number = 99.99
booleanAllowed values are True or False. The value is case-sensitive, so capitalize the first letter.is_active: mutable boolean = True
objectValue is a complex JSON object in the form {"key": "value"}.order_line: mutable object = {"SKU": "abc12344409","count": 42}
dateAny valid date format.start_date: mutable date
idDeprecated. Use string to store a Salesforce record ID.See string type.
list[type]A list of values of the specified type. All primitive types and object type are supported.flags: mutable list[boolean] = [True, False, True], scores: list[number] = [95, 87.5, 92], obj_list: mutable list[object] = None

Use None to check whether a variable has a value. You can use None with any variable type. For a string variable, you can also use "" to check if the variable is set to an empty string. When checking string variables in conditional statements, you might want to use both None and "".

For more information, see Agent Script Reference: Conditional Expressions.

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

The source field references where the variable gets its value. Supported source namespaces are:

NamespaceAvailable PropertiesDescription
@MessagingSessionId, MessagingEndUserId, EndUserLanguageProperties of the messaging session
@MessagingEndUserContactIdProperties of the messaging end user
@VoiceCallIdProperties of the voice call

Linked variables can have these types:

  • string
  • number
  • boolean
  • date
  • id (deprecated; use string for Salesforce record IDs)

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