---
title: "Create agent session"
method: POST
path: "/v2/agents/{agent_key}/sessions"
tags: ["Agent Sessions"]
---

# 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](https://docs.vectara.com/docs/agent-os/sessions#working-with-artifacts-in-sessions).

## Example request

```json
\$ 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.

## Path parameters

- `agent_key` string, required — A unique key that identifies an agent.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- CreateAgentSessionRequest — Request object for creating a new agent session.
  - `key` string — A unique key that identifies an agent session.
  - `name` string — Human-readable name for the session.
  - `description` string — 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.
  - `metadata` object — Arbitrary metadata associated with the session.
  - `enabled` boolean — Whether the session should be enabled upon creation.
  - `tti_minutes` integer — 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.
  - `secrets` object — 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.
  - `from_session` object — Create a new session by forking an existing one. By default, copies all visible events and artifacts from the source session without compaction. Optionally specify exactly one of include_up_to_event_id or compact_up_to_event_id to control which events are included and whether they are compacted. These two fields are mutually exclusive.
    - `agent_key` string — Agent key of the source session (defaults to current agent).
    - `session_key` string, required — Session key of the source session.
    - `include_up_to_event_id` string, nullable — Only include events up to and including this event ID from the source session, copying them verbatim. Events after this ID are excluded. If null (the default), all visible events are included. Mutually exclusive with compact_up_to_event_id.
    - `compact_up_to_event_id` string, nullable — Compact all source events up to this event ID into a summary instead of copying them verbatim. If null (the default), events are copied verbatim. Mutually exclusive with include_up_to_event_id.

## Response `201`

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

- AgentSession — A session for interacting with an agent. The session holds the agent's context.
  - `key` string, required — A unique key that identifies an agent session.
  - `agent_key` string, required — A unique key that identifies an agent.
  - `name` string, required — Human-readable name for the session.
  - `description` string — 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.
  - `metadata` object — Arbitrary metadata associated with the session.
  - `current_step_name` string, 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.
  - `enabled` boolean, 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_key` string — A unique key that identifies an agent.
  - `created_by_session_key` string — A unique key that identifies an agent session.
  - `tti_minutes` integer — 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_at` string, date-time, required — Timestamp when the session was created.
  - `session_context_usage` SessionContextUsage — Token usage of the session's most recent agent call, reflecting current context window consumption. Not a running total across calls.
    - `input_tokens` InputTokens — Input token usage details.
      - `count` integer — Number of input tokens consumed by the most recent agent call, including cached tokens.
      - `cached_tokens` integer — Subset of count served from the prompt cache. Omitted when no input tokens were served from the cache.
    - `output_tokens` OutputTokens — Output token usage details.
      - `count` integer — Number of output tokens generated by the most recent agent call.
      - `reasoning_tokens` integer — Number of tokens used for reasoning/thinking.
    - `total_tokens` integer — Input plus output tokens of the most recent agent call. Can be used with model_context_window to calculate context utilization percentage.
    - `model_context_window` integer — Maximum context window size in tokens for the model used by this session. Can be used with total_tokens to calculate context utilization percentage.
  - `effective_compaction` CompactionConfig — Configuration for automatic context compaction.
    - `enabled` boolean — Enable automatic context compaction.
    - `threshold_percent` integer — Context usage % (50-95) at which compaction is applied.
    - `keep_recent_inputs` integer — Number of recent turns to keep verbatim (not compacted).
    - `compaction_message` string — Custom additional instructions for the compaction summarization prompt.
    - `tool_event_policy` 'exclude' | 'include_outputs' | 'include_all' — How tool events are included in the compaction input.
  - `alias_key` string, 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`).
  - `secrets` object — 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.

## Other responses

- `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.
- `422` — A session_enrichment tool call has an invalid configuration or its transform raised an error, so no session was created. `messages` 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.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/e85040b266cc/schema)