How to Use Custom Values and Variables in Agent Studio
Introduction
Custom Values and Variables are the key to creating dynamic and adaptable workflows in Agent Studio. They act as intelligent placeholders that automatically pull live data into your agent’s conversations and actions, eliminating the need for manual, static text. This guide will show you how to leverage different types of variables—including Account details, Contact information, real-time dates, form submissions, and Custom Values—to make your agents more efficient and personalized.
Understanding Variables
A variable is a special tag, written inside double curly braces (e.g., {{contact.first_name}}), that gets replaced with actual data when your agent runs. For instance, a message that says Hello {{contact.first_name}} will appear as Hello Sarah when interacting with a contact named Sarah. You can insert these variables into any text field within Agent Studio, such as AI prompts, message cards, or conditional logic, by either clicking the dropdown arrow in the text editor or typing the braces manually.
Categories of Variables
Agent Studio provides several built-in categories of variables, each sourcing data from a different part of your system.
Custom Values
Custom Values are key-value pairs that you define and manage centrally. You can create them by navigating to Settings → Custom Values. Once created, they can be used across all your agents. For example, if you create a Custom Value with the key business_email and value info@yourcompany.com, you can insert {{custom_values.business_email}} anywhere in an agent. If you later update the email address, the change is reflected everywhere the variable is used automatically. Furthermore, agents using the AI Agent action can update these values on the fly using the Update Custom Value tool.
Account Variables
These variables pull information from your location’s settings, such as the business name, phone number, or website. Use variables like {{account.name}} or {{account.primary_phone}} to consistently reference your business details without hardcoding them.
Right Now Variables
Right Now variables insert real-time date and time information based on your location’s timezone. Examples include {{right_now.date}} for today’s date or {{right_now.time}} for the current time, ensuring your agent’s messages are always timely.
Form Data Variables
When an agent is triggered by a form submission, all the data from the form fields becomes available as variables. For a form field labeled “project_type,” you could use {{form.project_type}} to reference the user’s selection. Note that these variables are only populated when the agent is initiated by a form submission event.
Contact Variables
Contact variables pull data directly from the contact’s record in your CRM, including standard fields like {{contact.first_name}} and {{contact.email}}, as well as any custom fields you have created. This ensures that your agent uses the most up-to-date information from the contact’s profile.
Contact vs. Runtime Variables
It’s important to distinguish between Contact variables and Runtime variables. Contact variables reference data that is permanently stored in the contact’s CRM record. Runtime variables, on the other hand, hold temporary information that is gathered during the current conversation. Use Contact variables for pre-existing data and Runtime variables for values collected on the fly.
How to Set Up and Use Variables
Step 1: Create Custom Values
Go to Settings → Custom Values, click Add Custom Value, enter a Name and its corresponding Value, and then click Create.
Step 2: Open Your Agent
Navigate to AI Agents → Agent Studio and either create a new agent or open an existing one.
Step 3: Insert a Variable
Click inside any text field, such as a prompt or message. Then, either click the dropdown arrow that appears or type {{ to open the variable picker. Select the appropriate category (Account, Custom Values, Right Now, Form Data, or Contact) and choose the specific variable to insert it. Note that some nodes, like API Call steps, can generate their own runtime variables based on their output, which can then be used in subsequent steps.
Step 4: Save and Test
Click Save and then use the Test feature to run a sample conversation. Verify that all variables resolve to their expected values. If a variable appears blank, check that the corresponding data exists in your CRM or location settings.
Step 5: Publish
Once you have confirmed that everything is working correctly, promote your agent to the Production environment.
Frequently Asked Questions
What happens if a Custom Value is deleted?
If a Custom Value is deleted, any variable referencing it will return a blank value. This prevents errors and allows the agent to continue running.
Can I use variables for Opportunity or Task fields?
The currently supported variable sources are Account, Custom Values, Right Now, Form Data, and Contact.
What happens if a variable has no value?
If a variable is empty or missing, the system will simply return a blank string. This fail-safe design ensures your agent does not crash and can continue its execution smoothly.