Agent Script Reference: System Variables

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 custom variable or a linked variable

For custom and linked variable definitions, see Agent Script Reference: Variables (Custom and Linked).

@system_variables.user_input

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.

Note

Example - Analyze Customer Sentiment

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.

1reasoning:
2    actions:
3        AnalyzeSentiment: @actions.AnalyzeSentiment
4            with utterance = @system_variables.user_input
5            set @variables.customer_sentiment = @outputs.sentiment_classification

@system_variables.current_modality

The current_modality system variable indicates whether the agent is currently operating in voice or text mode. This variable is automatically populated on every inbound turn, based on the connection channel:

Connection Type	`current_modality` value
Telephony	`"voice"`
Messaging/Enhanced Chat v2	`"text"`

If your agent isn’t bound to a telephony or messaging/ECv2 connection, the current_modality system variable isn’t set (value is None).

Use this system variable when you want the agent to behave differently in different modes. For example, your agent can keep responses short and free of formatting on voice mode, but provide richer formatting responses during text mode.

Example - Adapt Response to Modality

In this example, we pass the current modality into an action so it can tailor its output:

1reasoning:
2    actions:
3        FormatResponse: @actions.FormatResponse
4            with modality = @system_variables.current_modality

@system_variables.current_connection

The current_connection system variable identifies the connected client for the current turn. This variable is automatically populated on every inbound turn.

This value may be unpopulated (None) until the runtime finishes configuring the connection.