Create agent session

POST 
/v2/agents/:agent_key/sessions

Creates a new session for interacting with an agent. A session maintains state across all events, tool use, and agent responses produced during the interaction.

You can set the session's 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. This supports 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

201

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

400

The request to create a session is malformed or references an invalid agent.

403

Permissions do not allow creating sessions for this agent.

404

Agent not found.

409

No session was created. Either the requested session key or name is already taken, or the agent's run_condition evaluated to false. messages names which. A collision needs a different key or name, while the same request succeeds after a run_condition refusal once the expression, or the metadata it reads, changes.

422

No session was created. A session_enrichment tool call has an invalid configuration or its transform raised an error, or the agent's run_condition returned a non-boolean. messages names the cause. For an enrichment failure it names the failing tool call and the reason, such as a $ref to a secret that is not on the agent or in the request, or a jq error raised by the called tool configuration's input_transform or output_transform.

502

A session_enrichment tool call failed upstream, so no session was created. The failure may be transient; retrying the request may succeed.

504

A session_enrichment tool call did not complete within its timeout_seconds, so no session was created.