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.

Chat with your agent

After creating an agent, you can interact with it by creating a session and sending messages. Sessions provide conversation context and are required for all agent interactions.

Create a session (UI)

1. Log into the Vectara Console.
2. Navigate to the Agents page.
3. Select an agent from the list such as Agent Research Assistant.
   The agent opens the Preview tab.
4. Chat with the agent in the Preview tab.
5. Upload artifacts (files) to the session, and chat about these artifacts with your agent.
   You can continue to configure and fine tune the agent through the Settings tab.

Create a session (API)

1. Send a POST request to the sessions endpoint.

   CREATE A SESSION

   Code example with multiple language options.bashjson

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

   SEND A MESSAGE

   Code example with multiple language options.bashjson

   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.bash

1

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

INSTRUCTION REFERENCING SESSION METADATA

Code example with json syntax.json

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.json

1