Sign in

v2

OpenAPI 3.0.02026-08-051996591.2 MB
Agent Sessions

Create agent session

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.

post/v2/agents/{agent_key}/sessions

Path parameters

agent_keystring required

A unique key that identifies an agent.

Example:customer_support

The unique key of the agent to create a session for.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

keystring

A unique key that identifies an agent session.

namestring

Human-readable name for the session.

descriptionstring

A short description of the session's purpose. If omitted, the platform generates one after the session produces events. Pass an empty string to suppress auto-generation.

metadataobject

Arbitrary metadata associated with the session.

enabledboolean

Whether the session should be enabled upon creation.

tti_minutesinteger

Time-to-idle in minutes for the session. If no events occur in the session for this duration, the session is deleted automatically. If set to 0, the session does not expire.

secretsobject

Session-scoped secrets to store on the new session. Map of secret name to plaintext value. Encrypted at rest with the owning agent's encryption key. Referenced from tool argument_override via {"$ref": "session.secrets.<name>"}. Returned masked (****) on reads.

Example request

{
  "key": "customer_support_chat",
  "name": "Customer Support Session",
  "description": "Helping customer troubleshoot issues",
  "metadata": {
    "customer_id": "12345",
    "priority": "medium",
    "channel": "web_chat"
  },
  "enabled": true,
  "tti_minutes": 60,
  "secrets": {
    "slack_user_token": "xoxp-your-token-here"
  }
}

Response

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

keystring required

A unique key that identifies an agent session.

agent_keystring required

A unique key that identifies an agent.

namestring required

Human-readable name for the session.

descriptionstring

A short description of the session's purpose. If omitted at creation, the platform generates one after the agent produces events. An empty string indicates auto-generation is disabled for this session.

metadataobject

Arbitrary metadata associated with the session.

current_step_namestring nullable

The step name the session will resume at on the next user message. If null, the session starts at the agent's first_step.

enabledboolean required

Whether the session is currently active and can accept new messages.

status'unstarted' | 'running' | 'stopped'

Lifecycle status of the session. unstarted before the session receives any event, running while the agent is producing events, and stopped when the session is idle with no event in flight. stopped implies no terminating action — the session returns to running on the next request.

created_by_agent_keystring

A unique key that identifies an agent.

created_by_session_keystring

A unique key that identifies an agent session.

tti_minutesinteger

Time-to-idle in minutes for the session. If no events occur in the session for this duration, the session is deleted automatically. If not specified, the session does not expire.

created_atstring date-time required

Timestamp when the session was created.

alias_keystring nullable

If this session was created through an alias (POST /v2/agent_aliases/{alias_key}/sessions), the alias key the caller used. The agent_key field above is the resolved agent the alias's policy picked. Null when the session was created directly under an agent (POST /v2/agents/{agent_key}/sessions).

secretsobject

Session-scoped secrets, with values masked as "****". Plaintext is never returned on read; tools resolve the real value via argument_override with {"$ref": "session.secrets.<name>"}. Set or rotate via the session create or update request.

Example response

{
  "key": "customer_support_chat",
  "agent_key": "customer_support",
  "name": "Customer Support Session",
  "description": "Helping customer troubleshoot widget installation issues",
  "metadata": {
    "customer_id": "12345",
    "priority": "high",
    "channel": "web_chat"
  },
  "current_step_name": "billing",
  "enabled": true,
  "status": "stopped",
  "created_by_agent_key": "customer_support",
  "created_by_session_key": "customer_support_chat",
  "tti_minutes": 60,
  "created_at": "2024-01-15T10:30:00Z",
  "session_context_usage": {
    "input_tokens": {
      "count": 120,
      "cached_tokens": 100
    },
    "output_tokens": {
      "count": 30
    },
    "total_tokens": 150,
    "model_context_window": 200000
  },
  "effective_compaction": {
    "enabled": true,
    "threshold_percent": 80,
    "keep_recent_inputs": 1
  },
  "alias_key": "support",
  "secrets": {
    "slack_user_token": "****"
  }
}