Variables are like containers that hold information your agent needs to remember and use throughout a conversation. They are essential for creating personalized, dynamic, and context-aware interactions.

​
Why variables matter

Personalization

Greet users by name, reference past interactions, and tailor the conversation to their specific context.

Memory & context

Remember user preferences, choices, and information provided earlier in the conversation.

Conditional logic

Direct the conversation flow based on variable values, creating different paths for different user segments or scenarios.

Data for analytics

Variable values are available at the end of each conversation for analysis and further actions (e.g., updating databases, triggering follow-ups).

​
How variables work

Pass data to agent

Feed initial information about the user or context into the agent at the start of the conversation (e.g., user name, order history).

Extract data from agent

Capture information gathered by the agent during the conversation (e.g., user’s address, reason for calling).

​
Identifying variables for your usecase

When planning your agent’s variables, think about the conversation flow and what information needs to be tracked. Here’s a structured approach:

​
Example: Cart abandonment agent

Let’s look at how this applies to an e-commerce cart abandonment agent:

Initial variables:

User context:

  • user_name
  • location
  • user_type (new/returning)

Cart details:

  • product_id
  • product_name
  • product_price
  • cart_total

Start with essential variables and add more as needed. It’s easier to add variables later than to manage unnecessary ones.

​
Using variables in agents

​
Referencing variables

Variables can be referenced in the greeting message, global insructions, and state instructions by typing ’@’ and selecting from the dropdown. You can choose to include the variable in either of two different formats—value or variable—and also select from any of the system variables.

Adding variables to state context

You can also include variables in a state’s context through the Variables in State dropdown without mentioning them in instructions. This gives the state access to these varibales and helps answer user queries using their context.

Note: Variables mentioned in the prompt are automatically added to state context.

​
Variable formats

When referencing variables in your instructions or greeting message, you can choose between two formats:

Value format

References the actual value of the variable in the prompt. Best for direct interactions and personalized messages.

Variable format

References the variable name as a placeholder. Best for performing operations on variables and logic control.

While you’ll select the format using the ’@’ dropdown on the platform, throughout this documentation:

  • Value format is shown as {{variable_name}}
  • Variable format is shown as variable:variable_name

Use when you want the agent to see and work with the actual data value.

Example:

"Hello {{user_name}}" → "Hello John"
"Your order total is {{cart_total}}" → "Your order total is $50.00"

Common scenarios:

  • Greeting messages
  • Order confirmations
  • Status updates

​
System variables

System variables like current_day, current_date, current_time, and current_datetime are available for use to give the agent context about the current time and date.

System variables are initialzed at the start of each conversation, and reset and the beginning of each new turn in the conversation.

​
Best practices

Clear naming: Use meaningful variable names that indicate their purpose

Think long-term: Consider what information will be valuable across interactions

Consistent formatting: Follow lower_snake_case convention (e.g., user_name, order_total)