Sign in

v2

latestOpenAPI 3.0.02026-08-051996591.2 MB
Agent Aliases

Create an alias

Creates an alias. An alias maps a public name to one or more underlying agents under a configurable policy. When you create a session through an alias (via POST /v2/agent_aliases/{alias_key}/sessions), the alias's policy selects the underlying agent that runs the session.

Common patterns:

  • Direct alias — a routed policy with one rule and one target. Identical in behavior to invoking the agent directly.
  • Canary rollout — a routed policy with one rule and multiple weighted targets (e.g. 90% v1, 10% v2).
  • Tenant routing — a routed policy with multiple rules, each matching on session metadata (e.g. session.metadata.tenant).
post/v2/agent_aliases

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

keystring required

The unique key that identifies an alias. Alias keys are independent of agent keys. The same string can exist as both an alias key and an agent key in the same customer account. Calls to /v2/agent_aliases/{key}/... target the alias. Calls to /v2/agents/{key}/... target the agent.

namestring required
descriptionstring
enabledboolean
metadataobject

Example request

{
  "key": "support",
  "policy": {
    "rules": [
      {
        "match": "(get('$.session.metadata.tenant') == 'us') and (get('$.session.metadata.tier') == 'gold')",
        "targets": {
          "partition_by": "get('$.session.metadata.user_id', '')"
        }
      }
    ]
  }
}

Response

The newly created alias.

keystring required

The unique key that identifies an alias. Alias keys are independent of agent keys. The same string can exist as both an alias key and an agent key in the same customer account. Calls to /v2/agent_aliases/{key}/... target the alias. Calls to /v2/agents/{key}/... target the agent.

namestring required

A human-readable name for the alias.

descriptionstring nullable

A longer description of what this alias represents.

enabledboolean required

Whether this alias is currently invocable.

metadataobject nullable

Arbitrary metadata associated with the alias.

created_atstring date-time required

Timestamp when the alias was created.

updated_atstring date-time nullable

Timestamp when the alias was last updated.

Example response

{
  "key": "support",
  "name": "Customer Support",
  "policy": {
    "rules": [
      {
        "match": "(get('$.session.metadata.tenant') == 'us') and (get('$.session.metadata.tier') == 'gold')",
        "targets": {
          "partition_by": "get('$.session.metadata.user_id', '')"
        }
      }
    ]
  }
}