End user sessions

Use end user sessions to let the people using your product talk to an agent directly from their own browser or mobile app. The end user's own credential creates, runs, and reads their own conversations, so your backend does not have to proxy every message, and the platform enforces that no end user can ever see another end user's sessions.

End users always reach an agent through an alias, never through an agent key. The alias is the public name you hand to your client; behind it you can re-route, split, or replace agents without changing anything the client calls.

Two ways to expose a session

Vectara agents expose sessions through two different surfaces, for two different callers.

	Operator sessions (/v2/agents/{agent_key}/sessions)	End user sessions (/v2/agent_aliases/{alias_key}/end_user_sessions)
Caller	Your backend, holding an API key	The person chatting with the agent
Visibility	Every event, including tool traces and reasoning	The conversation's messages, and nothing else
Ownership	Can act across any of your customer's sessions	Locked to the caller's own identity
Credential	API key or application client	A platform user holding agent_end_user, an anonymous widget visitor (an X-Visitor-Id minted at bootstrap), or a federated end user (a token from your own identity provider)

If your backend already mediates every message (for example, to inject session metadata for per-user access control), operator sessions are still the right surface. Reach for end user sessions when you want to hand the session credential directly to an untrusted client, such as a browser tab or a mobile app, and skip building your own proxy.

What end user sessions guarantee

A caller can only ever reach their own sessions

There is no parameter anywhere in this API for choosing whose sessions to read. The owning principal is stamped from the caller's authenticated identity when the session is created, and it can't be set or changed afterward. Listing sessions returns only the caller's own, and getting, sending to, or deleting a session owned by someone else returns 403, never that other person's data.

This isolates your end users from each other, not from you. An end user session is a regular agent session underneath, so it still appears in your own session list and in the Console, where your team can read it, inspect its full event history, and delete it. Plan for that when deciding what your end users are invited to type into a conversation.

End users see messages, and nothing else

The full agent event stream includes internal detail — reasoning traces, tool calls, step transitions, compaction — that isn't meant for an end user. End user sessions expose exactly three event types:

• input_message — what the end user said.
• agent_output — what the agent replied.
• error — a turn-ending failure signal, carrying a generic message that does not identify the underlying cause. Without it, a failed turn would be indistinguishable from one that simply produced no reply.

Every other event type is invisible to an end user, and there is no configuration that makes one visible. New event types are invisible by construction, so an agent that starts using one cannot start leaking it.

Grant a user access

An end user is any principal holding the agent_end_user role, scoped to one specific alias key. This role grants nothing else. A user account is the usual holder, but an API key, an application client, an anonymous widget visitor, or a federated end user may hold it too: each owns the sessions it creates and reaches no one else's. The other agent roles reach these operations as well, and an agent administrator is bound to its own sessions the same way; the operator endpoints under /v2/agents/{agent_key}/sessions remain the administrative view of an alias's sessions.

The role must name an alias. Granting it on an agent key is rejected — publish the agent behind an alias and grant on that alias key instead.

The role grants the end-user session operations of the alias it names and nothing else — not reading users, not creating API keys, not querying corpora. That is what makes the credential safe to hand to an untrusted client: adding agent_end_user to an account never widens what that account can reach.

You can hold it alongside other roles, which is useful for testing your own published agent from a developer account. Bear in mind that such an account still has everything its other roles grant, so for a credential you intend to ship to a browser or mobile app, give the end user their own account rather than adding the role to a teammate's existing one.

Grant access (Console)

1. Log into the Vectara Console.
2. Navigate to the Team page.
3. Select the user you want to grant access to.
4. Open the Agents access tab.
5. Click Grant access to agent, choose the alias, select Agent end user, and click Grant access.

Grant access (API)

Send a PATCH request to the user's endpoint with the role scoped to your alias's key.

GRANT THE AGENT_END_USER ROLE

Code example with multiple language options.bashjson

1

See Update user for the full request shape. The agent_key field carries the alias key here; agent keys and alias keys are separate namespaces for a customer.

Create a session and chat

Once a user holds the role, they authenticate as themselves and call the dedicated end user endpoints with their own credential.

CREATE A SESSION

Code example with multiple language options.bashjson

1

Every end user session belongs to a widget connector, which is what carries its settings (its idle lifetime, the event types it reveals, and the session_metadata written onto each of its sessions, which the agent reads as session.metadata.*). An alias has exactly one widget connector, and the session binds to the addressed alias's widget automatically — there is nothing to pass. The widget must be enabled, or the request is rejected with 400, as it is when the alias has no widget connector at all. name and description are optional; if you omit them, the server names the session for you and fills in a description once the agent has produced a response.

The alias resolves which agent handles the session once, at creation time. If you later shift the alias's routing, sessions created before the shift keep running on the agent they started with, and your client keeps calling the same alias URL throughout.

SEND A MESSAGE

Code example with multiple language options.bashjson

1

The response contains that turn's visible events. Sending a message while the session is already processing one returns 409. To attach files to a message, send the same request as multipart form data with one or more files parts.

Stream the response

Set stream_response to true on the same request to receive the reply as Server-Sent Events. Live text arrives incrementally as streaming_agent_output chunks, followed by the complete, persisted agent_output event.

STREAMING RESPONSE

Code example with bash syntax.bash

1

Limits

Each end-user principal has a per-customer cap on live sessions and on sessions created per hour. Exceeding either returns 429. Delete a session to free up capacity within the live-session cap; the hourly cap resets on a rolling basis.

A session's idle lifetime is not something the end user sets. It comes from the widget connector the session binds to: the widget's session_tti_minutes is applied to every session created through its alias, and the session is deleted automatically after that long without activity. The effective value is reported back as tti_minutes on the session object.

Next steps

• Agent aliases - the public name end users call, and how to route it to different agents.
• Sessions - the operator-facing session surface, and how to pass per-user identity through session metadata.
• Agent End User Sessions API reference - full request and response schemas for every operation.