Agent aliases

An agent alias is a stable public name that routes each new session to an underlying agent according to a policy you control. Callers address the alias, not a specific agent, so you can shift traffic between agents, run canary rollouts, or send different tenants to different agents without changing the caller.

You create sessions through an alias with POST /v2/agent_aliases/{alias_key}/sessions. The alias evaluates its policy, picks the agent that owns the session, and from then on the session behaves like any other agent session. To configure routing, see Route sessions with an alias.

Why it matters

Without an alias, every caller hardcodes a specific agent_key. Changing which agent serves traffic means redeploying every caller. An alias adds one level of indirection so routing changes happen on the server.

This makes three patterns possible without touching client code:

• Canary rollouts. Send a percentage of sessions to a new agent version, watch it, then shift the weight.
• Tenant routing. Route sessions to different agents based on session metadata such as tenant or tier.
• Stable handles. Keep one public name in front of an agent whose configuration evolves over time.

How it works

An alias holds a routing policy of type routed. The policy is an ordered list of rules. When a session is created through the alias, the rules are evaluated top to bottom and the first rule that matches decides where the session goes.

Rules

Each rule has an optional match expression and a targets block.

• match is a UserFn expression that evaluates to a boolean. The first rule whose match is true is selected. A rule with no match is a catch-all that always applies. It must be the last rule in the policy. Any rule placed after a catch-all is rejected as unreachable.
• targets is either single (route directly to one agent_key) or weighted (split across several agents by weight).

The match expression uses the get() function with JSONPath to read the routing context. The same UserFn language powers the user-defined function reranker. The context available at routing time is:

{
  "agent":   { "name": "...", "key": "...", "description": "...", "metadata": {} },
  "session": { "key": "...", "name": "...", "description": "...", "metadata": {} },
  "currentDate": "2026-01-15T10:35:00Z"
}

note

At routing time the underlying agent has not been picked yet, so agent.* reflects the alias's own metadata, with the alias key in agent.key. Use session.* for per-call routing inputs such as tenant or user id, which is what most rules dispatch on. A missing path returns null, and comparing against null is false, so the rule falls through to the next one. Use get('$.path', 'default') to supply an explicit fallback.

Weighted targets

A weighted target splits traffic across several agents. It declares a partition_by UserFn expression and a list of options, each with an agent_key and a non-negative integer weight.

At routing time the alias evaluates partition_by, hashes the result, and uses the hash to pick one option in proportion to the weights. partition_by sets the unit the split is computed over: every session whose partition_by evaluates to the same value resolves to the same option, as long as the weights do not change. Choose get('$.session.key') to split per session, or get('$.session.metadata.user_id', '') to send all of a user's sessions to the same agent. This determinism is a property of the weighted split itself. It is separate from session resolution, which is always fixed at creation regardless of partition_by.

If partition_by evaluates to null, the request is rejected. Wrap optional fields with a default, for example get('$.session.metadata.user_id', ''), so every session resolves to a stable value.

Resolution is fixed at session creation

Routing runs once, when the session is created. The resolved agent_key is written onto the session and never re-evaluated. Replacing the policy later (see Route sessions with an alias) only affects sessions created after the change. Sessions already created keep the agent they resolved to.

The session returned from an alias carries both the resolved agent_key and the alias_key it was created through. You can address the session either through the alias at /v2/agent_aliases/{alias_key}/sessions/{session_key} or directly through its agent at /v2/agents/{agent_key}/sessions/{session_key}.

Aliases and agents share no namespace

Alias keys and agent keys are independent. The same string can name both an alias and an agent in the same account. Calls to /v2/agent_aliases/{key}/... target the alias, and calls to /v2/agents/{key}/... target the agent.

An alias can only reference agents that exist in your account. Creating or updating a policy that names an unknown agent returns 400 with Alias references unknown agent(s): [...]. An agent that is referenced by an alias cannot be deleted until the reference is removed.

When to use an alias

Use case	Why an alias fits
Roll out a new agent version gradually	A weighted target shifts a percentage of sessions to the new agent, with the rest staying on the current one.
Serve different tenants from different agents	Ordered rules match on session.metadata and route each tenant to its agent.
Keep one public name in front of an evolving agent	Callers address the alias while you swap the underlying agent behind it.
Combine the above	Each rule independently uses a single or weighted target, so you can canary inside one tenant while routing others directly.

Key terms

Term	Definition
alias_key	The unique key identifying an alias, independent of agent keys.
policy	The routing configuration. Currently always type: routed.
rule	An optional match expression plus a targets block. Rules are evaluated in order.
match	A UserFn expression evaluating to a boolean. Omit for a catch-all rule.
catch-all	A rule with no match. Always applies, and must be last.
single target	A direct route to one agent_key.
weighted target	A split across several agents selected by hashing partition_by.
partition_by	A UserFn expression whose value is hashed to pick a weighted option.

Related guides

• Route sessions with an alias
• Sessions
• Agent concepts
• Agent Aliases API reference