> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# Variants

> 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.

Variants is for agents that serve 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.

Variants is found under **Knowledge > Variants** in Agent Studio.

**Use Variants 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 [FAQs](/agent-studio/knowledge/fa-qs/fa-qs) and [functions](/agent-studio/tools/overview) directly.

![variant-1](/_fern-files/_img/b91b4feda94403e34948711cd6d2b6423086e0108e1bae45337a08695462ecbd.webp)

## Prerequisites

1. Ensure you have admin access to **Knowledge > Variants** in your PolyAI agent.
2. Set up [FAQs](/agent-studio/knowledge/fa-qs/fa-qs) aligned with your multi-site configuration goals.
3. Understand how to use [functions](/agent-studio/tools/overview) in your agent.

To bulk update or create variants, use the [CSV import guide](/agent-studio/knowledge/variants/csv-imports).

## Key capabilities

### Multi-site configurations

Use **Variants** to manage multiple locations in 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 Variants are accessible in your FAQs rules, templates, and actions using the `${variant_<attribute_name>}` syntax. The `variant_` prefix is required – an attribute named `opening_hours` is referenced as `${variant_opening_hours}`, not `${opening_hours}`. In Python functions, the same attribute is accessed without the prefix as `conv.variant.opening_hours`.

### Flexible routing

Set up routing in the [start function](/agent-studio/tools/start-tool) 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 tailor SMS messages dynamically.

### Advanced functions

Use the [`conv.variant`](/agent-studio/tools/classes-and-objects/object#set-variant) object to retrieve variant attributes during conversations or make decisions based on variant data.

### 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, letting you test variant-specific behavior directly in Agent Studio without manual function workarounds.

> **Warning**
>
> 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](/agent-studio/tools/start-tool).

## 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 Variants table like a spreadsheet:

* **Add variant** (with 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** (with 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.

![variant-2](/_fern-files/_img/2ad00d9531b9120666b1f5b7fe57e9d397e0dd8faad2b9e243907e5711ce5546.webp)

### Setting up a new variant

![variant-3](/_fern-files/_img/9890ad0da539402086cbe19ed4c5ba75fc6191b82e25f02ee6b668abdf58c8bf.webp)

To configure variants:

1. Open **Knowledge > Variants** in the sidebar.
2. Add a new variant and provide a name, such as "London" or "Tokyo."
3. Save your configuration.

![variant-4](/_fern-files/_img/4e91f34719a9268e011d0e926ad11c7ccf9bf1c5c0322145978a92ac6dbe7a2d.webp)

### Setting up a new attribute

![variant-5](/_fern-files/_img/f765f418ed4b818cb8fb7bd04eae7a5289bcd8dc320e7c83af520b58baf57501.webp)

Define attributes for the variant, such as:

* **Phone numbers**
* **Address**
* **Operating hours**
* **Menu**
* **Accessibility**

![variant-6](/_fern-files/_img/c991fe31a56562d529574064cb7d7c6d500d2040933114a4eec32f0314218fcc.webp)

> **Note**
>
> **Attribute values are stored as strings.** Whatever you type or paste into the Variants table — including JSON, dict literals, comma-separated lists, or numbers — is persisted verbatim as a string and returned as a string from `conv.variant.<attribute>`. To use structured data:
>
> * Store it as **JSON** (use `null`, not `None`; lists, not tuples) and parse with `json.loads()` in your function, or
> * **Split** structured values into multiple attributes (for example `tuesday_open`, `tuesday_close`) so each cell holds a single scalar value.
>
> Reading an attribute that does not exist on the active variant returns `None`, not an `AttributeError`.

### 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**:

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

## Using variants in SMS templates

Main article: [SMS](/agent-studio/voice/message-templates)

To include variants dynamically in SMS messages, use the syntax `${variant_<attribute_name>}` (the `variant_` prefix is required). For example:

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

The same `variant_`-prefixed syntax works in FAQs rules, templates, and actions. Inside Python functions, the prefix is dropped: `conv.variant.phone_number`.

## 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:

```python
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 shows how to assign variants dynamically based on user context. The `conv.variant` object lets you retrieve and set the appropriate variant so responses match the user's location or context.

### Voice example (phone number-based)

Match the dialled number against a variant attribute to set the active variant. The attribute name (e.g., `phone_number`, `callee`) must match a column you defined in **Knowledge > Variants**.

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

If your variant table uses a different column name for the phone number (for example, `callee`), replace `variant.phone_number` with `variant.callee`:

```python
def start_function(conv: Conversation):
    callee_map = {
        variant.callee: variant_name
        for variant_name, variant in conv.variants.items()
    }
    if conv.callee_number and conv.callee_number in callee_map:
        conv.set_variant(callee_map[conv.callee_number])
```

### Webchat example (URL parameter-based)

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

```python
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 control which [flows](/agent-studio/flows/overview) 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 lets you enable or disable specific conversation paths per location or configuration without duplicating flow logic.

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

## Automate with the Agents API

If your variants live in a source of truth outside Agent Studio — a locations database, a CRM, a spreadsheet — you can sync them directly rather than editing by hand.

#### Manage variants via the Agents API

The [Agents API](/api-reference/build-deploy/agents-api/overview) exposes full CRUD for both [attributes](/api-reference/api-reference/agents/attributes/list) (the dimensions) and [variants](/api-reference/api-reference/agents/variants/list) (the per-site combinations).

**`curl`**

```bash curl
# Create an attribute (a variant dimension)
curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches/main/attributes \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "location_id" }'

# Create a variant with attribute values
curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches/main/variants \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "London Flagship",
    "attributes": {
      "location_id": "LON-01",
      "address": "12 Regent Street",
      "hours": "9am - 10pm"
    }
  }'
```

**`Python`**

```python Python
import os, requests

BASE = "https://api.us.poly.ai"
HEADERS = {"x-api-key": os.environ["POLYAI_API_KEY"]}

# Sync many sites in one pass
for site in load_locations_from_crm():
    requests.post(
        f"{BASE}/v1/agents/{AGENT_ID}/branches/main/variants",
        headers=HEADERS,
        json={
            "name": site["name"],
            "attributes": {
                "location_id": site["id"],
                "address": site["address"],
                "hours": site["hours"],
            },
        },
    )
```

## Related pages

#### [CSV imports](/agent-studio/knowledge/variants/csv-imports)

Bulk create or update variants using CSV files.

#### [FAQs](/agent-studio/knowledge/fa-qs/fa-qs)

Use variant attributes in topic responses with \$\{variant_attribute} syntax.

#### [Functions](/agent-studio/tools/overview)

Access variant data programmatically with conv.variant.

#### [Start tool](/agent-studio/tools/start-tool)

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

#### [Variants endpoints](/api-reference/api-reference/agents/variants/list)

CRUD for variants and attributes in the Agents API.