Route sessions with an alias

Use this guide to put an alias in front of your agents and route sessions through it. An alias is a stable public name whose policy decides which agent owns each new session. For the routing model and terminology, see Agent aliases.

By the end, you will be able to:

• Create a direct alias that forwards every session to one agent.
• Run a canary rollout that splits traffic between two agent versions by weight.
• Route sessions to different agents based on session metadata.
• Flip routing later by replacing the policy, with no change to callers.

Before you begin

You need:

• A Vectara account (sign up free for a 30-day trial).
• VECTARA_API_KEY set as an environment variable.
• The agent_developer or agent_administrator role, or an account role of administrator or owner.
• At least one existing agent. These examples use the agent keys support-v1 and support-v2. Substitute your own.

Step 1: Create a direct alias

Start with a policy that has one rule, a catch-all (no match), and a single target. Every session created through this alias goes to one agent. This behaves exactly like calling the agent directly, and gives you a stable name to evolve later.

curl -X POST https://api.vectara.io/v2/agent_aliases \
  -H "x-api-key: $VECTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "support",
    "name": "Customer Support",
    "description": "Stable public handle for the support agent",
    "policy": {
      "type": "routed",
      "rules": [
        { "targets": { "type": "single", "agent_key": "support-v1" } }
      ]
    }
  }'

Expected response:

{
  "key": "support",
  "name": "Customer Support",
  "description": "Stable public handle for the support agent",
  "policy": {
    "type": "routed",
    "rules": [
      { "targets": { "type": "single", "agent_key": "support-v1" } }
    ]
  },
  "enabled": true,
  "metadata": {},
  "created_at": "2026-06-02T10:35:00.000Z"
}

The response returns 201. If the policy names an agent that does not exist, the call returns 400 with Alias references unknown agent(s): [...]. If an alias with this key already exists, it returns 409.

Step 2: Create a session through the alias

Send a session create request to the alias instead of an agent. The alias resolves its policy and returns a session owned by the chosen agent.

curl -X POST https://api.vectara.io/v2/agent_aliases/support/sessions \
  -H "x-api-key: $VECTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support conversation",
    "metadata": { "tenant": "us" }
  }'

Expected response:

{
  "key": "ase_support_conversation_1c2e",
  "agent_key": "support-v1",
  "alias_key": "support",
  "name": "Support conversation",
  "metadata": { "tenant": "us" },
  "enabled": true,
  "created_at": "2026-06-02T10:35:44.637Z"
}

The session carries both the resolved agent_key and the alias_key it was created through. From here you submit input and read events exactly as with a direct agent session, either through the alias path /v2/agent_aliases/support/sessions/{session_key}/events or through the agent path /v2/agents/support-v1/sessions/{session_key}/events.

Step 3: Run a canary rollout

To roll out a new agent version gradually, replace the single target with a weighted target. Weights are non-negative integers normalized at routing time, so 90 and 10 send roughly 90 percent of sessions to support-v1 and 10 percent to support-v2.

curl -X PUT https://api.vectara.io/v2/agent_aliases/support/policy \
  -H "x-api-key: $VECTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "type": "routed",
      "rules": [
        {
          "targets": {
            "type": "weighted",
            "partition_by": "get('"'"'$.session.key'"'"')",
            "options": [
              { "agent_key": "support-v1", "weight": 90 },
              { "agent_key": "support-v2", "weight": 10 }
            ]
          }
        }
      ]
    }
  }'

partition_by sets the unit the weighted split is computed over. Every session whose partition_by resolves to the same value goes to the same option. The table shows the common choices.

partition_by expression	Splits traffic by	When to use
get('$.session.key')	Session	Split sessions across versions independently.
get('$.session.metadata.user_id', '')	User id	Send all of a user's sessions to one version.
get('$.session.metadata.tenant', '')	Tenant	Move whole tenants together.

caution

partition_by is required for a weighted target, and must not evaluate to null. A request whose partition_by resolves to null is rejected with 400. Wrap optional metadata fields with a default, for example get('$.session.metadata.user_id', ''), so every session resolves to a stable value.

To shift more traffic to the new version, replace the policy again with new weights, for example 50 and 50, then 0 and 100. The change is atomic. Sessions already created keep the agent they resolved to. Only new sessions use the updated weights.

tip

This canary is one stage of a larger loop: clone an agent, canary it, ramp, promote the winner, and retire the old version. For the full lifecycle, keeping each caller on one version, rollback, and cleanup, see Alias workflows and best practices and the Canary an agent version tutorial.

Step 4: Route by tenant

To send different tenants to different agents, use multiple rules. Rules are evaluated top to bottom and the first matching rule wins. End with a catch-all rule so every session has a fallback.

curl -X PUT https://api.vectara.io/v2/agent_aliases/support/policy \
  -H "x-api-key: $VECTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "type": "routed",
      "rules": [
        {
          "match": "get('"'"'$.session.metadata.tenant'"'"') == '"'"'us'"'"'",
          "targets": { "type": "single", "agent_key": "support-v1" }
        },
        {
          "match": "get('"'"'$.session.metadata.tenant'"'"') == '"'"'eu'"'"'",
          "targets": { "type": "single", "agent_key": "support-v2" }
        },
        {
          "targets": { "type": "single", "agent_key": "support-v1" }
        }
      ]
    }
  }'

A session created with metadata.tenant of us resolves to support-v1, eu resolves to support-v2, and anything else falls through to the catch-all. Each rule can independently use a single or weighted target, so you can canary inside one tenant while routing others directly.

Verify the result

Create a session through the alias and confirm the resolved agent in the response.

curl -X POST https://api.vectara.io/v2/agent_aliases/support/sessions \
  -H "x-api-key: $VECTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "EU check", "metadata": { "tenant": "eu" } }'

A successful result shows:

• agent_key set to the agent the policy selected, for example support-v2 for the eu tenant.
• alias_key set to support.

Troubleshooting

Issue	Cause	Fix
400 Alias references unknown agent(s): [...]	A target names an agent that does not exist in your account.	Create the agent first, or correct the agent_key.
400 rule #N follows a catch-all rule and is unreachable	A rule is placed after a rule with no match.	Move the catch-all rule to the end of the list.
400 partition_by is required.	A weighted target omits partition_by.	Add a partition_by expression to the weighted target.
400 no rule matched and no catch-all rule was provided	A session's context matched no rule and the policy has no catch-all.	Add a catch-all rule (a rule with no match) as the last rule.
400 partition_by evaluated to null	partition_by read a missing metadata field.	Supply a default, for example get('$.session.metadata.user_id', '').
409 Alias '...' already exists	The alias key is already in use.	Choose a different key, or update the existing alias.

What you created or changed

• An alias named support that callers address instead of a specific agent.
• A routing policy that you can replace at any time to canary, shift weights, or route by tenant, with no change to callers.

Related guides

• Agent aliases
• Alias workflows and best practices
• Tutorial: Canary a new agent version
• Sessions
• Define session context with session metadata
• Agent Aliases API reference