Skip to main content
Version: 2.0

Sessions

Agents keep track of their conversations with sessions. One conversation is one session. To begin chatting with an agent, you need to create a session first. Each message sent by the user and each response from the agent is appended to the session. Sessions also provide a workspace for artifacts, allowing agents to work with uploaded documents and images throughout the conversation.

  • A session key and human-readable name (ase_12345). If not provided, Vectara generates one automatically based on the name.
  • Associated agent_key (agt_abcd).
  • Metadata such as end_user_id, application_id, priority, or channel.
  • Timestamps for creation and last update.

Sessions support lifecycle operations such as creation, update, retrieval, listing, and deletion.

Chat with your agent​

After creating an agent, you can interact with it by creating a session and sending messages:

1. Create a session​

Sessions provide conversation context and are required for all agent interactions:

CREATE A SESSION

Code example with multiple language options.
1

2. Send messages to the agent​

Once you have a session, send messages using the events endpoint:

SEND A MESSAGE

Code example with multiple language options.
1

The agent will respond with events including its reasoning, tool usage, and final response.

You can also upload files (documents and images) to the session workspace using multipart requests. See Artifacts for details on working with files in agent sessions.

Define session context with session metadata​

Let's say you want to make the agent aware of the user's preferred language, so that it can respond in that language. Or imagine you want to tell the agent that the user is only permitted access to a specific type of data. You can do all this with session metadata. Session metadata enables you to inject arbitrary information into the session context, which your instructions and tools can refer to.

Session metadata provides context-specific data to agents, enabling personalization, security controls, and dynamic behavior. This key-value data attaches to a session and becomes accessible as follows:

  • Agent instructions (Velocity templates) using ${session.metadata.field} syntax
  • Tool configurations (argument overrides) using {"$ref": "session.metadata.field"} syntax

Here's how you might implement the language preference and access control examples.

Example session with metadata​

SESSION WITH COMPREHENSIVE METADATA

Code example with bash syntax.
1

Then you'd write an instruction like this, to respond in the preferred language.

INSTRUCTION REFERENCING SESSION METADATA

Code example with json syntax.
1

And you'd configure a corpora search tool like this, to limit the user's access to certain corpora.

TOOL WITH METADATA-BASED ACCESS CONTROL

Code example with json syntax.
1