Variables

To improve security and ensure consistent agent behavior, use variables throughout your agent’s reasoning and interactions, such as in filters, instructions, and logical expressions.

Required Editions

Available in: Lightning Experience

Available in: Enterprise, Performance, Unlimited, and Developer Editions. Required add-on licenses vary by agent type.

A context variable, also called a linked variable, is mapped to an object field. For example, Agentforce Service agents include context variables that are mapped from Messaging Session object fields, including custom fields. Agents with the Telephony connection also include context variables that are mapped from Voice Call object fields.

For example, this Agent Script defines a context variable that stores the messaging session record ID and a context variable that stores the voice call record ID.

RoutableId: linked string
    description: "The messaging session ID"
    label: "RoutableID"
    source: @MessagingSession.Id
VoiceCallId: linked string
    description: "The voice call ID"
    label: "VoiceCallId"
    source: @VoiceCall.Id

A custom variable, also called a mutable variable, is unique to the agent that it's in, and it holds a value only during the conversation session. Custom variables can store one of these data types: string, number, list, object, boolean. By default, these variables are internal only, meaning that they can only be set in the agent. You can make them external, meaning that they can also be set with the Agent API.

For example, this Agent Script defines a custom string variable that stores a user's name.

userName: mutable string
    description: "The name of the user"
    label: "Name"
    visibility: "External"

System variables are predefined and hold a value only during the conversation session. These variables are read-only.

Here are some Agent Script examples of how you can use variables throughout your agent’s reasoning and interactions.

Set a variable to an action input or output. The action uses the set variable’s value as input, or stores the output value in the set variable.
```
run @action.Get_Order_Details
    with order_number=@variables.orderNumber
    set @variables.order_id=@outputs.order_id
```

Use a variable in a filter.

get_order_details: @actions.Get_Order_Details
    available when @variables.isVerified == False

Use variables in logical expressions.

if @variables.order_summary == "":
    run @actions.lookup_current_order
      with member_email=@variables.memberEmail
      set @variables.order_summary=@outputs.order_summary

Set variable values.

set @variables.userName = ”New User”

Use variable values in agent responses. For example, you can tell the agent to use a variable in a specific way in subagent instructions.
```
| Refer to the user by the name {!@variables.userName}.
```

Use a system variable to tell the agent about the current session. For example, tell the agent to format dates differently for a text or voice conversation in agent-level instructions.

if @system_variables.current_modality == "text":
    | Format dates in a readable format, such as "8/17/2025".
if @system_variables.current_modality == "voice":
    | Format dates for speech, such as "August seventeenth 2025".

Create Variables in Agentforce Builder
Use variables to store and reuse values in your agent’s reasoning and control how an agent makes decisions. For example, when you assign a variable to an action input, your agent can use only the assigned variable to fill the value of the input.