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

# Tutorial: Variants

> PolyAcademy Level 2 – Use variants to manage site-specific, brand-specific, or channel-specific content.

**Level 2 – Lesson 7 of 8** – Tailor agent responses for different contexts without creating separate projects.

> **Lesson**
>
> Level 2 · Intermediate · 15 min

[Variants](/agent-studio/knowledge/variants/overview) let you maintain **one agent** while tailoring responses for different contexts – no separate projects needed. A variant is a **named configuration profile** that changes selected content or settings depending on where or how the agent is used.

## Common use cases

#### Site/location

Different branches, properties, campuses, stores

#### Brand

Same company, different sub-brands with different tone or policies

#### Region

Differences in hours, terminology, supported services, legal language

#### Channel

Chat vs Call wording; short vs spoken-friendly phrasing

#### Audience segment

B2B vs B2C, member vs non-member

## What variants are (and aren't)

#### What variants ARE

#### Configuration profiles

A **set of values** attached to a variant name (for example: `site_name = "Example site"`), used to customize how the agent responds in that context.

#### Consistency tool

A way to keep **shared logic and behavior consistent**, while allowing specific fields to differ.

#### Analysis dimension

Visible during analysis: variants appear in Conversation review/diagnosis, showing which context handled each turn.

#### What variants are NOT

> **Warning**
>
> * **Not separate agents** - They share the same core configuration
> * **Not environments** - Sandbox/Pre-release/Live are about safe promotion; variants are about contextual behavior
> * **Not a retrieval fix** - Variants should refine, not rescue, retrieval

## How the Variant UI works

#### Empty state

When no variants exist, you'll see a primary **Add Variant** button.

#### Table/grid view

When variants exist:

* Each row is a variant (for example, `Site 1 (default)`)
* Columns represent variant fields/attributes (for example, `site_name`, plus other fields your org has defined)
* A search bar for finding variants quickly

#### Edit variant panel

Often a right-side drawer containing:

* **Variant name (required)**: the label you will recognize in testing and reporting
* **Default variant** toggle: marks which variant is used when no other variant is selected
* Editable fields such as `site_name`, and any other attributes your configuration supports

#### Import / Export controls

Useful for bulk setup (many sites/locations) and sharing configurations across environments or projects.

## When to use variants

#### Use variants when

* You have **repeatable structure** but different values
* You want to avoid copying the same Managed Topic content across multiple projects
* You need to test and report on performance by context

#### Avoid variants when

* The differences are **so large** that you effectively have a different agent
* You are trying to solve a retrieval problem that should be fixed by better topic names

#### Check your understanding

#### You have 20 hotel properties and each has different check-in times, addresses, and front desk numbers. You're considering creating 20 separate agent projects. What's a better approach?

* Create 20 projects – one per property
* Use variants to store property-specific values in a single agent
* Use Response Controls to switch between properties
* Create environment-specific configurations for each property

**Answer:** Use variants to store property-specific values in a single agent

Variants let you maintain one agent while tailoring responses for different contexts. Creating 20 separate projects would mean duplicating all shared logic and making maintenance much harder.

## Planning your variant strategy

Before creating anything, define one sentence your team agrees on:

**"A variant represents \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_."**

**Examples:**

* "A variant represents a single hotel property."
* "A variant represents a specific store location."
* "A variant represents a brand under a multi-brand umbrella."

This prevents "variant sprawl," where variants become an unstructured dumping ground.

## Create your first variant

#### Open Variants

Navigate to **Knowledge > Variants** in the platform.

#### Click Add Variant

Start the variant creation process.

#### Configure variant settings

Set:

* **Variant name**: use a naming convention that scales
* **Default variant**: set one default so testing and Live always have a predictable fallback
* **Key fields**: start with 1–3 fields that clearly affect behavior

### Naming conventions that scale

#### Stable and sortable

`site_001_downtown`

Good for large deployments with many locations

#### Human-friendly

`kansas_city`

Consistent with your existing naming conventions

#### Multi-dimensional

`brand_a_us`

If your dimension is brand + region

## What to put into variants

Variants are most useful for content that is:

* Frequently repeated in calls/chats
* Specific to context
* Risky if wrong

#### Good variant fields

#### Location identifiers

`site_name`, `city`, `region`

#### Customer-facing facts

`hours`, `address`, `parking_info`, `accessibility_info`

#### Escalation language

"connect you to the front desk" vs "connect you to an agent"

#### Channel-specific phrasing

Short, spoken-friendly alternatives for Call

#### Avoid varying

> **Warning**
>
> **Content you usually should NOT vary:**
>
> * Broad agent role and overall scope (keep consistent across variants unless you truly operate different agents)
> * Safety policies
> * Core tone guidelines (small adjustments are fine; wholesale tone shifts are not)

## Testing variants

#### Switch to a non-default variant

Select a variant other than your default

#### Run your tests

Execute the same tests you used earlier:

* Simple FAQ (Chat and Call)
* Multiturn FAQ
* SMS/handoff topic phrasing (where relevant)
* Any brand-sensitive language (greeting, disclaimers, closings)

#### Verify behavior

Confirm:

* Switching variants changes **only what you intended**
* Core behavior remains consistent (no missing topics, no broken escalation language)
* In Conversation review/diagnosis, you can clearly see which variant handled the interaction

## Operational tips

#### Start small

Keep the number of variant fields small at first. Add fields only when you have a clear use case.

#### Store facts

Prefer storing factual, high-impact values (hours, addresses, names) rather than duplicating full KB answers.

#### Use Import/Export

When onboarding many variants at once; it reduces manual errors and makes review easier.

#### Maintain a default

Always maintain a **Default variant** so there is a safe fallback when context is missing or misconfigured.

#### Check your understanding

#### What are variants for?

* Creating separate agent projects for each location
* Testing different LLM models in production
* Tailoring agent responses for different contexts without creating separate projects
* Rolling back to a previous published version

**Answer:** Tailoring agent responses for different contexts without creating separate projects

A variant is a named configuration profile – same core agent, different values for specific fields. This avoids project sprawl when you need context-specific behavior.

## Try it yourself

#### Challenge: Design a variant strategy for a hotel chain

You are deploying one agent for three hotel properties: The Linden (London), The Linden (New York), and The Linden (Tokyo).

Answer:

1. Write your one-sentence variant strategy statement.
2. List **3 fields** that belong in variants.
3. List **1 field** that should NOT be in variants – and explain why.

#### Hint

Think about what changes per property (hours, address, local phone number) vs what should stay the same (core agent role, safety rules, overall tone).

#### Example solution

1. **Strategy:** "A variant represents a single Linden Hotel property."

2. **Fields in variants:**
   * `hotel_name` (e.g., "The Linden London")
   * `check_in_time` / `check_out_time`
   * `front_desk_phone`

3. **Should NOT be in variants:** Safety policies (e.g., "Never share guest information"). These are non-negotiable constraints that should apply identically across all properties.

#### Check your understanding

#### Which type of content is best suited for variants?

* Core safety policies and compliance language
* The agent's overall tone and personality
* Location-specific facts like hours, addresses, and escalation language
* LLM model selection per session

**Answer:** Location-specific facts like hours, addresses, and escalation language

Safety policies and core tone should NOT vary. Location-specific facts – hours, addresses, escalation language – are frequently repeated, context-specific, and risky if wrong, making them ideal candidates for variants.

#### [← Previous: Global ASR](/academy/poly-academy/poly-academy-level-2/global-asr)

Lesson 6 of 8

#### [Next: Advanced diagnostics →](/academy/poly-academy/poly-academy-level-2/conversation-reviews-advanced)

Lesson 8 of 8