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.

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

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

Working with artifacts in sessions​

Sessions provide a workspace where agents can access and process files uploaded by users or generated by tools. These files are stored as artifacts that enable efficient file handling without bloating the agent's context.

To make files available to an agent, upload them to the session workspace using a multipart request. Files are stored as artifacts and can be referenced throughout the conversation.

After files are uploaded as artifacts, the agent can extract content from PDFs, Word documents, or PowerPoint files and reference artifacts during conversations. Artifacts remain available throughout the session lifecycle, enabling multi-step workflows without re-uploading files.

Uploading files to a session​

To make files available to an agent, upload them to the session workspace using a multipart request. Files are stored as artifacts and can be referenced throughout the conversation.

UPLOAD FILES TO SESSION

Code example with bash syntax.
1?

The response contains an ArtifactUploadEvent with references to all uploaded files. This event becomes part of the session history, making the agent aware of the available files:

ARTIFACT UPLOAD EVENT

Code example with json syntax.
1

How agents use artifacts​

After files are uploaded as artifacts, the agent can:

  • Use document conversion tools to extract content from PDFs, Word documents, or PowerPoint files
  • Reference artifacts in analysis or question-answering workflows
  • Pass artifacts to indexing tools to add content to corpora
  • Create new artifacts as outputs of tool operations

Artifacts remain available throughout the session lifecycle, enabling multi-step workflows without re-uploading files.