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

Exactly one variant should have is_default: true.

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: "[phone]"
      london: "[phone]"
      tokyo: "[phone]"

  - 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
• rules
• greeting messages
• disclaimer messages
• personality custom
• role custom

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.

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 |-
• every variant must have a value for every attribute

Missing values will fail validation

If a variant is missing from an attribute’s values map, validation will fail.

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

Related pages

Topics

See how variant attributes are used in topic actions.

Voice settings

Use variant attributes in greetings and disclaimers.

Variant management (platform)

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