Skip to content

Variants

Variant attributes provide per-variant configuration so prompts and behavior can change by location, environment, or tenant without separate code or deployments.

At runtime, the platform selects a variant, and the agent reads the attributes associated with that variant.

Location

Variant attributes are defined in:

config/variant_attributes.yaml

What the file contains

The file has two top-level keys:

  • variants
  • attributes

Variants

The variants section defines the available variants.

Each variant includes:

Field Required Description
name Yes Unique identifier for the variant
is_default No Marks the fallback variant used when no variant is resolved at runtime

Attributes

The attributes section defines the values that vary by variant.

Each attribute includes:

Field Description
name Attribute identifier, ideally in snake_case
values Map from variant name to string value

Every attribute must provide a value for every defined variant, even if that value is an empty string.

Example

variants:
  - name: new_york
    is_default: true
  - name: london
  - name: tokyo

attributes:
  - name: office_phone
    values:
      new_york: "+12125551234"
      london: "+442071234567"
      tokyo: "+81312345678"

  - name: office_hours
    values:
      new_york: "9am - 5pm EST"
      london: "9am - 5pm GMT"
      tokyo: "9am - 5pm JST"

  - name: greeting_name
    values:
      new_york: "New York Office"
      london: "London Office"
      tokyo: "Tokyo Office"

  - name: custom_disclaimer
    values:
      new_york: |-
        This call is recorded for quality assurance.
        You may request a copy of this recording.
      london: |-
        This call may be recorded in accordance with UK regulations.
      tokyo: ""

Why variants are useful

Variants let one agent behave differently in different contexts without duplicating the whole project.

  • Branding

    Change names, labels, or brand-specific wording.

  • Contact details

    Swap phone numbers, addresses, and office hours.

  • Environment-specific behavior

    Store values such as region codes, timezones, or flags.

  • Multi-tenant setups

    Reuse the same logic with tenant-specific values.

Using variant attributes in prompts and resource files

Use {{attr:attribute_name}} in supported text fields such as:

  • flow step prompts
  • topic actions (not in content or example_queries)
  • rules (rules.txt)
  • persona (persona.txt)
  • greeting (welcome_message)
  • disclaimer message

Example

Our office number is {{attr:office_phone}}. We're open {{attr:office_hours}}.

Using variant attributes in Python

In code, variant values are read from conv.variant:

phone = conv.variant.office_phone
hours = conv.variant.office_hours

Use the same attribute names that are defined in variant_attributes.yaml.

To switch the active variant at runtime, call:

conv.set_variant("london")

Typical attribute types

Common uses include:

Category Examples
Branding greeting name, company name
Contact phone numbers, addresses, office hours
IDs location ID, region code
Feature flags "True" / "False" strings, checked in Python
URLs portal links, payment links
Environment timezone, is_live

Important formatting notes

  • variant names with special characters should be quoted
  • multi-line values should use |-

Validation

  • Exactly one variant must have is_default: true — validation fails if zero or more than one variant is marked default.
  • Every variant must have a value in every attribute's values map — a missing variant fails validation.

Best practices

  • keep variant names stable over time
  • set exactly one default variant
  • provide a value or "" for every variant in every attribute
  • prefer {{attr:...}} over hard-coded strings when values vary by location or environment
  • use multi-line YAML for disclaimers, instructions, or longer text values

  • Topics

    See how variant attributes are used in topic actions. Open topics

  • Voice settings

    Use variant attributes in greetings and disclaimers. Open voice settings

  • Variant management (platform)

    How variants are routed at runtime — SIP header routing, default selection, and conv.variant access. Open variant management