get_ab_test_variant

get_ab_test_variant(context: dict, test_name: str, possible_variants: list) -> str

Randomly assigns a variant to the conversation and remembers the assignment for future calls. Each conversation always gets the same variant for a given test name.

Parameters

Name	Type	Description
`context`	`dict`	The context object passed to your action
`test_name`	`str`	Unique identifier for this test (e.g., `"retention_flow_v2"`)
`possible_variants`	`list`	List of variant names (strings) or variant dicts with weights

Variant formats

Variants can be simple strings (equal weight) or dicts with explicit weights:

# Equal weights — each has 33% chance
["control", "variant_a", "variant_b"]

# Weighted — variant_a has 50% chance, others 25% each
[
    "control",                          # weight defaults to 1
    {"name": "variant_a", "weight": 2},
    {"name": "variant_b"},              # weight defaults to 1
]

Weights are relative. In the weighted example above, the total weight is 4, so variant_a (weight 2) has a 2/4 = 50% chance.

Returns

str — The name of the selected variant.

Error handling

Raises ValueError if possible_variants is empty.
Raises ValueError if a dict variant is missing the "name" key.
Raises ValueError if a weight is negative.

Side effects

On first call for a given test_name:

Randomly selects a variant based on weights
Stores the assignment as conversation metadata (key: ab_test:{test_name})
Tags the conversation with ab:{test_name}:{variant_name}
Records a conversation event: A/B test '{test_name}': assigned variant '{variant_name}'

Subsequent calls with the same test_name return the stored assignment without re-randomizing.

Examples

A/B test a retention flow

def evaluate_conditions(context):
    variant = get_ab_test_variant(context, "retention-flow", ["a", "b"])

    return {
        "conditions": {
            "isVariantA": variant == "a",
            "isVariantB": variant == "b",
        },
        "data": {},
    }

Weighted test with a control group

def evaluate_conditions(context):
    variant = get_ab_test_variant(
        context,
        "refund-offer",
        [
            {"name": "control", "weight": 3},   # 60%
            {"name": "generous", "weight": 1},   # 20%
            {"name": "minimal", "weight": 1},    # 20%
        ],
    )

    return {
        "conditions": {
            "isControl": variant == "control",
            "isGenerous": variant == "generous",
            "isMinimal": variant == "minimal",
        },
        "data": {"abVariant": variant},
    }

Use in an action to vary behavior

def execute_action(context):
    variant = get_ab_test_variant(context, "discount-level", ["10pct", "20pct"])

    discount = 10 if variant == "10pct" else 20
    result = apply_discount(context["args"]["orderId"], discount)

    return {"discount": discount, "result": result}

get_ab_test_variant

On this page