About

You can insert variables into your agent's playbook to personalize conversations and provide real-time user context to your agent. When someone interacts with your agent, variables are automatically filled in with relevant information, such as their name, job title, company, or session details.

You configure variables in the Playbook tab within the following fields:

• Agent role (up to 2,000 characters) - Instructions that define the agent's persona, behavior, and role during conversations.
• Opening phrase (up to 200 characters) - The greeting spoken by the agent when a conversation starts.
  

Access the Playbook tab

1. From the Agents tab, click the agent you want to configure.

   
   The agent workspace opens on the Overview tab.

2. Click the Playbook tab.

   

   The Playbook tab displays.
   

   

Insert a variable

You can add built-in system variables while editing the Agent role or Opening phrase fields.

1. In the Agent role or Opening phrase field, place your cursor where you want to insert a variable and type {{. A menu opens showing available System variables and Custom variables.
   

   

2. Start typing to filter the list.
3. (Optional) Hover over a system variable to view a card with its description and an example value.
   

   

4. Click the variable or press Enter to insert it. The variable appears wrapped in double brackets (for example, {{sys__user_obj.first_name}}).
   

   

Create custom variables 

If your setup passes extra information into the conversation, such as a customer tier or campaign name, you can use it by creating custom variables directly in the Agent role or Opening phrase fields.

1. In the Agent role or Opening phrase field, type {{ followed by the name of your new custom variable (for example, {{customer_tier).
   

   

   The new custom variable is added under Custom variables with a "New" tag. 

2. Click on the new custom variable in the menu or type }} to close the brackets. Spaces are automatically converted to underscores (_). 
   

   

   The custom variable is added to the agent's catalog and can be reused across both the Agent role or Opening phrase fields for this agent.

Example configurations

Agent role

You are a product onboarding specialist assisting an employee from {{sys__user_obj.company}}. 
Tailor your explanations and technical depth to someone in the role of {{sys__user_obj.title}}. 
Address the user by their first name, {{sys__user_obj.first_name}}.

Opening phrase

Hi {{sys__user_obj.first_name}}, welcome to Kaltura! I am your AI assistant. How can I help you today?

Guidelines and variations 

• Character limits: Variable text counts toward the character limit of the field (up to 200 characters for Opening phrase and up to 2,000 characters for Agent role).
• Closing brackets: Every variable must be closed with  }}. The Studio flags unclosed brackets and prevents you from publishing until they are resolved.
• Editing variables: Variables behave as editable plain text. You can select, backspace, copy, or delete them directly in the text field.

Publish your changes

Adding, editing, or removing variables in your playbook is treated as an unpublished change. Click Publish at the top right to apply your changes.

Until you publish your changes, they won't affect conversations with your agent.