Version: 2.0

Agent Aliases

Manage routing aliases that map a public name to one or more agents under a configurable policy. Create a session through an alias (POST /v2/agent_aliases/{alias_key}/sessions) and the alias's policy picks the underlying agent that runs.

📄️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.

📄️List aliases

Lists aliases. Results are paginated.

📄️Get an alias

Returns the alias, including its policy.

📄️Update an alias's metadata

Updates an alias's metadata fields (name, description, enabled, metadata). To replace the routing policy, use `PUT /v2/agent_aliases/{alias_key}/policy`. Policies are atomic and do not support partial updates.

📄️Delete an alias

Deletes an alias. The underlying agents the alias points at are not affected. Returns 409 if any live resources still reference this alias.

📄️Replace an alias's routing policy

Replaces the alias's routing policy and stickiness configuration in one atomic operation. The replacement is whole-object. Partial merging is not supported.

📄️Create session via alias

Creates a session by routing through an alias. The alias's policy selects the underlying agent that owns the session. Subsequent operations on the session can use this alias or the direct path `/v2/agents/{resolved_agent_key}/sessions/{session_key}`.

📄️List sessions routed via this alias

Lists sessions originally created via this alias (sessions whose `alias_key` matches). Sessions are also reachable under their resolved agent's URL. This endpoint is the alias-scoped view.

📄️Get alias-routed session

Returns a session originally created via this alias.

📄️Update alias-routed session

Updates a session originally created via this alias.

📄️Delete alias-routed session

Deletes a session originally created via this alias.

📄️Submit input to alias-routed session

Submits an input event to a session originally created via this alias. The session's resolved agent processes the event.

📄️List events on alias-routed session

Lists events of a session originally created via this alias.

📄️List outstanding client tool calls on alias-routed session

Lists the client tool calls that a session originally created via this alias waits on the caller to fulfill. Each entry carries the fully materialized arguments to invoke the tool with. Secret-derived values are returned unmasked because the caller needs them to execute the tool. This endpoint therefore requires the same roles permitted to submit input to the session. The list is empty when the session is not parked on a client tool. See the agent-scoped endpoint for the full contract.