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.

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
• Sessions
• Define session context with session metadata
• Agent Aliases API reference