Skip to main content
Version: 2.0

Create agent session

POST 
/v2/agents/:agent_key/sessions
Supported API Key Type:
Personal

Create a new session for interacting with an agent. A session is the conversation container that maintains state across all messages, events, tool use, and agent responses.

This endpoint initializes the session and enables you to configure its initial properties, including optional metadata. Metadata can influence agent behavior, personalize responses, or apply access controls. Instructions and tools can also reference metadata using ${\session.metadata.field} or $\ref syntax.

A session also serves as the workspace for artifacts, enabling file uploads and multi-step workflows. For more information, see Working with artifacts in sessions.

Example request​

\$ curl -X POST https://api.vectara.io/v2/agents/support-agent/sessions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "key": "user_12345_session",
  "name": "Customer Support Session",
  "metadata": {
    "user_role": "premium",
    "language": "en"
  }
}'

A successful response includes the unique session key, configuration metadata, and timestamps for creation and last update.

Request​

Responses​

The response includes the complete session configuration including the unique session key, associated agent key, and creation timestamp.

Last updated on by Paul Wozniczka