Surface Variants

Rolling out a new model, provider, or guardrail posture usually means redeploying a client or creating a parallel endpoint. Surface Variants let any Surface carry more than one behavior behind the same route, so callers do not need to change the base URL they use. Roll out a new model with a canary split →

Surface Variant

A Surface Variant is a named variation on a base Surface, selected through a route-level alias such as {route}$alias/..., without creating a separate Surface record. It can expose a different provider, model, guardrail, budget, Judge, Jury, policy, cache, alert, or timeout without duplicating the base configuration that would otherwise diverge over time.

Overrides are sparse: a variant changes only the fields it needs and inherits the rest from the base Surface. Each variant has its own name, URL alias, and description, and administrators select the variant they want to edit in the Surface editor. Because it keeps the base Surface’s identity and routing fields, it is reached through the same base route and observed under the same metrics. Each resolved base, variant, or inline target has its own executor and response-cache identity, so concurrent requests cannot reuse another target’s provider or cached answer.

Test changes before promotion

Variants support development, staging, and production postures; tier-specific access such as free and pro; progressive rollout; and dual-persona A/B tests.

For example, an administrator can create a variant from a production Surface, change it to use a new frontier model or stricter guardrail, and validate the result without affecting production callers. Traffic addressed to the base route keeps using the base configuration, while callers that address the variant alias use the new posture. When the change is ready, promote the variant to become the default. New traffic arriving at the Access Point then uses the promoted configuration without changing the route or breaking existing callers.

Selecting a variant automatically

A client can address a variant explicitly with $alias, but a surface can also select one automatically, using two mechanisms that apply before the model is called:

A canvas variant switcher lets you pick which variant to edit; the canary split itself lives on the surface’s own configuration panel:

Which selection mechanism wins

An explicit $alias in the route always wins. If none is given, the first matching routing rule wins. If no routing rule matches, the canary split applies.

Why this matters

• Routing rules let you tier traffic without redeploying a client, for example routing a X-Tier: pro header to a better model, or a batch-flagged request to a cheaper one.
• Canary splits let you dark-launch a new guardrail posture or provider at a small percentage of traffic and watch its cost, latency, and rejection figures before promoting it to every caller.

Both are measured per variant in Observability →, so a rollout’s effect is visible from the first request. Once a variant proves out, it can be promoted to become the surface’s new default through the same variant CRUD used to create it, closing the loop from experiment to standard behaviour.

Turning canary off is non-destructive: routing stops immediately, but the stored split percentages and the variants themselves are left untouched, so re-enabling restores the previous split.

Related

• Surfaces: How a variant relates to its parent surface.
• IDE Surface: A surface type that can use variants for its own governed model menu.
• Resilience and caching: How a load-balanced pool differs from a routing rule or canary split.
• Observability: Where per-variant metrics appear.
• LLM drift detection: How replaying a surface’s captured traffic through a candidate variant checks a change against a baseline before it takes live traffic.