Overview

Manage multi-site configurations for a single agent.

Some sections on this page require Python. Default variant handling, testing with functions, and the advanced conv.variant examples need Python familiarity. The UI-based setup (creating variants, adding attributes, CSV imports) does not require code.

Use variant management when a single agent serves multiple locations, brands, or configurations. Each variant stores attributes like phone numbers, addresses, and hours, so one agent can give the right answer for each site. Without variants, you would need a separate agent per location — multiplying maintenance and increasing the risk of inconsistencies.

Variant management is found under Build > Variant management in Agent Studio.

Use variant management when your agent needs location- or site-specific responses (hours, addresses, phone numbers). If your agent serves a single location, you do not need variants — use Managed Topics and functions directly.

Prerequisites

1. Ensure you have admin access to Build > Variant management in your PolyAI agent.
2. Set up Managed Topics aligned with your multi-site configuration goals.
3. Understand how to use functions in your agent.

To bulk update or create variants, use the CSV import guide.

Key capabilities

Multi-site configurations

Use variant management to manage multiple locations within the same agent. Attributes such as phone numbers and opening hours are stored per variant, so the agent gives location-specific answers.

Knowledge integration

Attributes defined in variant management are accessible in your Managed Topics rules, templates, and actions. For example, you can use ${variant_foo} to populate responses dynamically with location-specific information.

Flexible routing

Set up routing in the start function to direct users to the appropriate variant. For voice, route based on phone numbers or SIP headers; for webchat, use URL parameters or session data. Variants can also be used to tailor SMS messages dynamically.

Advanced functions

Use the conv.variant object to retrieve variant attributes during conversations or to make decisions based on variant data. Use functions to set, retrieve, or act on variant-specific attributes.

Testing and troubleshooting

You can select a specific variant when making in-app test calls. The variant selector appears in the Call configuration section when variants exist for your project. This allows you to test variant-specific behavior directly in Agent Studio without manual function workarounds.

The first variant created is used as the default for the agent. If this variant is deleted, the next variant in the list automatically becomes the new default. To control which variant is active, use conv.set_variant() in your start function.

Real-life use case

A hotel chain with multiple branches worldwide uses Variant Management to manage its agent. Each branch (e.g., “London” and “New York”) has a variant configured with attributes like phone numbers, addresses, and check-in hours. When a guest contacts the agent, the branch is identified based on the user’s context—phone number for voice, URL parameters for webchat—and the response is tailored accordingly.

Variants and attributes

Think of the variant management table like a spreadsheet:

• Add variant (via the Add variant button) adds a new row. Each variant represents a distinct location or site, such as “London” or “Tokyo.” It is the who — a new instance of the configuration.
• Add attribute (via the + plus sign) adds a new column. Each attribute is a data field that exists across all variants, such as phone number, address, or operating hours. It is the what — a new piece of information that every variant can hold a value for.

Setting up a new variant

To configure variants:

1. Open Build > Variant management in the sidebar.
2. Add a new variant and provide a name, such as “London” or “Tokyo.”
3. Save your configuration.

Setting up a new attribute

Define attributes for the variant, such as:

• Phone numbers
• Address
• Operating hours
• Menu
• Accessibility

Default variant handling

By default, the first variant in the list is used unless otherwise specified. If a variant needs to be changed programmatically, use the conv.set_variant() method in your start function.

Example:

if not conv.variant:
    conv.set_variant("default_variant_name")

Using variants in SMS templates

Main article: SMS

To include variants dynamically in SMS messages, use the syntax ${variant_attribute}. For example:

• ${variant_phone_number} dynamically includes the phone number associated with the active variant.

Testing variants

In-app calling

When making test calls from Agent Studio, you can select a specific variant from the Call configuration section. The variant selector only appears when variants exist for your project. Call settings are grouped in a collapsible panel for easier navigation.

In chat

For webchat testing, you can set variants manually in the start function:

if not conv.callee_number:
    conv.set_variant("London")

Alternatively, create functions such as set_variant1, set_variant2 to switch variants during testing.

Advanced: Accessing variants in functions

This example demonstrates how to dynamically assign variants based on user context. Using the conv.variant object, you can retrieve and set the appropriate variant to ensure responses are tailored to the user’s location or context.

Voice example (phone number-based)

def start_function(conv: Conversation):
    phone_numbers = {
        variant.phone_number: variant_name
        for variant_name, variant in conv.variants.items()
    }
    if conv.callee_number:
        conv.set_variant(phone_numbers[conv.callee_number])

Webchat example (URL parameter-based)

For webchat interactions, you can use URL parameters or session data to determine the variant:

def start_function(conv: Conversation):
    # Get variant from webchat metadata (e.g., URL parameter)
    location = conv.metadata.get("location")
    if location and location in conv.variants:
        conv.set_variant(location)

Flow activation per variant

Variants can control which flows are available during a conversation. Each variant supports two fields:

• active_flows — a list of flow names that are enabled for this variant
• inactive_flows — a list of flow names that are disabled for this variant

When a variant is active, only its active_flows are available to the agent. Any flows listed in inactive_flows are skipped during processing. This allows you to enable or disable specific conversation paths per location or configuration without duplicating flow logic.

# Check which flows are active for the current variant
if conv.variant:
    active = conv.variant.active_flows
    log.info(f"Active flows: {active}")

Related pages

CSV imports

Bulk create or update variants using CSV files.

Managed Topics

Use variant attributes in topic responses with $ syntax.

Functions

Access variant data programmatically with conv.variant.

Start function

Route callers to the correct variant based on phone number or metadata.