Context Variables

Every customer is unique, and your agent may choose to treat them as such where appropriate.

Context variables enrich the context that an agent sees about the customer it's talking to. They're meant to give your agent awareness to information that helps it personalize its service, much like how a thoughtful customer service representative knows and remembers important details about each client, to make them feel heard and understood.

When a customer interacts with an agent, their context variables are automatically loaded into its context, allowing the agent to tailor its responses based on their specific situation.

Real World Applications

Let's walk through how context variables transform customer interactions. Imagine you're running a SaaS platform's support agent. You might track variables like subscription plan, last login date, which features each customer uses, and their company size.

Consider two different customers reaching out about data exports. Sarah, a startup founder on the free plan, asks "Can I export my data to Excel?" Your agent, aware of her free plan status, can respond thoughtfully: "While Excel export is a premium feature, I can show you how to use our basic CSV export. Would you also like to learn about the advanced reporting capabilities in our premium plan?"

Now imagine Tom from an enterprise account reaches out with the same question. The agent sees his enterprise status but also notices his team hasn't explored many advanced features. It might respond: "I'll help you with Excel exports! I notice your team hasn't tried our automated reporting suite yet - this is included in your enterprise plan and could save you hours each week. Would you like me to show you both features?"

Working with Context Variables

A single context variable identifies a particular piece of information. For example, you might create a variable called "subscription_plan".

Each customer can then have a unique value assigned to them under that context variable. For example, Tom might have "enterprise" as the variable's value.

Here's how to create a new context variable for a specific agent and assign a value to a customer:

parlant variable create \
  --tag agent:AGENT_ID \
  --name VARIABLE_NAME \
  --description VARIABLE_DESCRIPTION # Optional

parlant variable set --id VARIABLE_ID --key CUSTOMER_ID --value VARIABLE_VALUE

Alternatively, you can also create tags for customers—say, to assign them to groups—and then to configure variable values for tags (customer groups) instead of individual customers.

parlant variable set --id VARIABLE_ID --key TAG_NAME --value VARIABLE_VALUE

Combining Context Variables with Guidelines

Let's explore how guidelines and context variables work together to create truly intelligent interactions. Imagine you're running an AI support agent for a digital bank where customers have different account tiers and transaction patterns.

Here's a focused guideline:

Condition: customer's account tier is 'basic' AND they ask about instant international transfers

Action: Highlight our same-day domestic transfers that are free on their plan, then mention how premium enables instant global payments

When Mark asks about sending money to his daughter studying abroad, instead of a flat "that's premium only" response, he hears: "I can help you send that money today using our standard international transfer. By the way, our premium accounts get this done instantly with lower fees—would you like to know more?"

For high-value customers who haven't explored wealth management:

Condition: customer's balance is at least 100k AND they aren't using our investment products

Action: After you're done helping them with their inquiry, mention our personalized investment advisory service

So when Jessica checks her substantial balance, the agent notes: "I see you've built up some significant savings. Did you know our wealth management team can help create a personalized investment strategy for you?"

Dynamic Variable Values with Tools

A key part of optimizing how agents adapt to customers is using customer-specific data. However, some customer data changes dynamically.

For example, a retail store agent could notify the customer when an item in their cart goes out of stock. To do this, the agent needs to be constantly aware of the items in the customer’s cart and their current availability.

While you could create an always-active guideline associated to a tool which checks for cart items going out of stock, there's a more elegant solution to this problem.

Using Tool-Enabled Context Variables, you can update contextual information from a dynamic data source, ensuring the agent is always aware of this information during the conversation. You can also control the variable's refresh interval using its freshness rules.

In our mock tech store scenario, instead of relying on guideline triggers for these checks, a tool-enabled context variable ensures that the agent automatically receives regular updates. This approach significantly reduces overhead.

Creating a Tool-Enabled Context Variable

You can create tool-enabled context variables by simply specifying the names of the tool and its containing service when creating the variable.

parlant variable create \
  --tag agent:AGENT_ID \
  --name VARIABLE_NAME \
  --service SERVICE_NAME \
  --tool TOOL_NAME

By default, the associated tool would executes any time the value is needed (i.e., on every agent response). If this frequent reload of data is unnecessary, you can control the refresh interval of the value (controlling how often the associated tool is called to generate a fresh value) by specifying its freshness rules.

parlant variable create \
  --tag agent:AGENT_ID \
  --name VARIABLE_NAME \
  --service SERVICE_NAME \
  --tool TOOL_NAME
  --freshness-rules CRON_EXPRESSION

Freshness rules follow the cron expression syntax. If you're new to cron, you can use tools like crontab generator to help you define the period syntax more easily.