Variables in AI Agents

15 min

Variables in Bot Mandate (AI Agent)

Variables let your bot remember a value, such as a phone number or an order ID, and reuse it anywhere in the conversation.

Variables already work in NLP flows. They are now available in AI Agents too, so one value can travel from an NLP flow to an AI Agent, into an API call, and back into another flow. This guide covers what variables are, how to create and use them, and a full API example.

What are variables?

A variable is a named slot that holds one value. Your bot has a single shared list of variables, used by both NLP flows and AI Agents. A variable created in one place is visible in the other, so a customer is never asked for the same detail twice.

Variables can be filled from four sources: details your website or channel already knows, the customer's own answers, an NLP flow, and API responses. Once filled, a value can be used in your AI Agent instructions, sent to an API, and read by any flow.

Create a variable in AI Agent

Option 1:

While writing. In an Objective, type / and choose Variable. Search the list, or choose + Create new variable at the end.

Option 2:

From the Available Variables section on the RHS panel. Expand Available Variables (collapsed by default), then click Create Variable. The section also lists every variable in the bot, with search.

Setting	What it does
Name	Must be unique in the bot, with no spaces, for example mobilePhone. To pre-fill it automatically, use exactly the name your website or channel sends.
Type	String, Number, Boolean, Object or Array, as in NLP flows.
Initial value	Optional starting value.
Is Cached	On: the value is kept for the whole conversation and is guaranteed to carry between NLP flows and AI Agents. Off: the AI Agent still remembers it during its own conversation, but it is not guaranteed to carry across.

Variables cannot be edited or deleted after they are created, so check the name, type and Is Cached setting before you save. For anything shared between flows and agents, turn Is Cached on.

Use variables in an AI Agent

Variables can be inserted in 3 places:

The Supervisor Objective - Type /, choose Variable, and pick one. It appears as a chip in your text. Hover over the chip to see its type, cache setting and source. Press Backspace once to remove it. In the examples below, bold words mark variable chips.

The AI Agent Objective - Same flow as the Supervisor Objective

Argument Description - Choose whether you want to describe the rule for the argument or mention the Variable to it.

Example Objective: "Greet the customer by firstName. If accountType is premium, offer priority support."

Fill variables automatically

Website: your website passes details such as mobilePhone or customerId when the chat loads (your developer can use EasyChat.init, and your Exotel contact can share the snippet). Matching variables are filled before the first message.

Channel: trusted details from the channel, such as the verified WhatsApp sender number, fill a variable with the matching name.

The customer: tell the agent to ask for a missing value and save it.

An API response: covered below.

Text a customer types is never treated as trusted channel information.

Variables are read and written the same way on both sides, so values follow the customer. Example journey:

An NLP flow collects orderId and the customer taps a Quick Reply button with the action (which Transfers to AI Agent).

The AI Agent starts with the conversation so far and the collected variables. It uses orderId without asking again.

The agent shows a button with the type Trigger Flow, such as "Raise a complaint". The complaint flow starts and reads orderId and any values the agent saved, such as orderStatus.

Customer moves from	To	Cached variable	Non-cached variable
AI Agent	AI Agent	Kept	Kept
AI Agent	NLP flow	Kept	Not guaranteed
NLP flow	AI Agent	Kept	Not guaranteed
NLP flow	NLP flow	Kept	Works as it does today

Use variables with APIs: full example

An order-tracking bot should answer "Where is my order?" using the customer's phone number and order ID, then reuse the result in a complaint flow. There are three parts:

pass values into the call

save the response in variable

use the saved values

Step 1. Create the variables

Variable	Type	Is Cached	Filled by
mobilePhone	String	On	Website, when the chat loads
orderId	String	On	The customer, or an NLP flow
orderStatus	String	On	API response
deliveryDate	String	On	API response
trackingUrl	String	On	API response

Step 2. Pass variables into the API call

In the AI Agent, open the action Get order details. Fill in the Action Description, request type, URL and headers as usual.

Then list the arguments.

For each one, the Argument Description says which variable supplies it and what to do if it is empty.

Argument	Argument Description (type / to insert variable chips)
mobile_number	Use mobilePhone. If it is missing, ask the customer for their registered mobile number, save it, then continue.
order_id	Use orderId if it already has a value. Otherwise ask the customer for their order ID and save it. If they want to check a different order, confirm and replace it.

The Action Description can say when to call it, for example "Use this when the customer asks about the status or delivery of an order." Headers stay simple name and value pairs.

Step 3. Save the API response into variables

Open the Response Variable section. Under Complete response, select a variable such as orderResult to keep the whole answer. Then turn on Save response fields to variables and add one row per value you need. Your API answers like this:

{ "status": "Shipped", "delivery": { "expected_date": "18 Oct" }, "tracking": { "url": "https://track.example.com/AB123" } }

Response path	Save to variable
status	orderStatus
delivery.expected_date	deliveryDate
tracking.url	trackingUrl

Paths can be a top-level field (status), a nested field with dots (delivery.expected_date) or an item in a list by position (items[0].name). If a path is not found, the conversation continues and that variable stays empty. Rows with only one side filled are not saved.

Step 4. Use the saved values

In the AI Agent Objective: "After the Get order details action, tell the customer the order status, orderStatus, and the expected delivery date, deliveryDate. Offer the tracking link, trackingUrl."

In an NLP flow such as "Raise a complaint", use orderId and orderStatus in messages and API calls the same way you already use NLP variables. No extra set-up is needed, because the list is shared.

What the customer sees

A logged-in customer asks "Where is my order?". The bot already has mobilePhone and asks only for the order ID.

The bot calls the API, saves the values, and replies: "Your order is Shipped and expected on 18 Oct. Track it here: https://track.example.com/AB123".

The customer taps "Raise a complaint". The complaint flow starts with the order ID and status already filled in.

A second question about the same order skips the questions, because the values are kept.

Best practices, limits and rules

Search the variable list before you create a new one, and choose names carefully because they cannot be changed yet.

Turn Is Cached on for anything shared across flows and agents.

For every API argument, say what to do when the value is missing, and whether to reuse, confirm or replace an existing value.

Save only the response fields you will reuse.

Rule	Detail
Names	Unique in the bot. Invalid names are not accepted. Must match exactly for automatic pre-fill.
Edit and delete	Not available yet. You can only add or remove where a variable is used.
Scope	One shared list for the whole bot. Values belong to one customer's conversation.
API arguments	Variable use is described in the Argument Description. There are no separate value-source controls per argument.
Response paths	Top-level, dotted nested, and list position.
Privacy	Values follow your normal masking and retention rules. Sensitive values such as tokens stay hidden.

Troubleshooting

What you see	Likely cause and fix
Variable not pre-filled	The name does not match what your website sends, or the variable does not exist. Compare names letter by letter and create it if missing.
Bot asks for something it should know	The variable is empty at that point. Check its source in Available Variables and add "use it, if missing ask" to the Argument Description.
Value empty after an API call	The response path was not found, the row is incomplete, or the toggle is off. Compare the path with your API's real answer.
Value lost between a flow and an agent	Is Cached is off. Create a new variable with it on, and use that one.
Cannot create a variable	The name is already used or invalid, or you do not have edit access to the bot.

FAQs

Are NLP variables and AI Agent variables different? No. They are one shared list.

Do I need a developer? Only to pass website details when the chat loads. Everything else is set up on the Bot Mandate screens.

Can I keep the whole API answer? Yes. Enter a name under Complete response, and add field rows only for values you want separately.

What if my website sends a detail I have no variable for? It is not used. Create a variable with the same name first.