Creates a session instance that binds an agent with a runtime environment. A full snapshot of the agent's latest version is captured at session creation. Session-level agent configuration overrides and MCP request headers are supported.
Prerequisites
Endpoint and authentication configuration must be completed. For details, see Overview and authentication. Before creating a session, you need an agent and an environment. For details, see Agent and Environment.
Endpoint
POST /sessions
Request body
| Field | Required | Type | Description |
|---|---|---|---|
agent | Yes | object | The bound agent reference object; pass only id to simply reference the agent. Can pin a version and optionally establish session-level overrides—see Session-level configuration overrides |
environment_id | Yes | string | The bound environment ID. If the environment has pre-installed packages configured, warm-up may be required after creation; a preparing environment cannot be bound to sessions (returns invalid_parameter), so wait for warm-up to complete |
title | No | string | Session title for easy identification in lists |
resources | No | array | Resources to mount at creation. File items contain type (fixed as file), file_id (uploaded file ID), and mount_path (mount path; must start with /uploads/, the actual path is prefixed with /mnt/session); memory store items contain type (fixed as memory_store), memory_store_id, access (read_only / read_write, defaults to read_write), and instructions (mount instruction, up to 4096 characters), with the mount path generated by the server from the store name. See Memory Store |
vault_ids | No | array of string | Vault ID list. Injects credentials from the specified vaults into the session runtime environment, allowing the agent to access the corresponding secrets |
metadata | No | object | Custom key-value pairs for business use; does not affect model behavior |
environment_variables | No | object | Environment variables injected into the session runtime as string key-value pairs; sandbox code can read them directly by name |
mcp_configs | No | array | Session-level MCP request headers, independent of agent—see Session-level MCP request headers. Defaults to an empty array when omitted |
Request example
Session-level configuration overrides
The agent object can simply reference the agent, or carry override fields to establish session-level overrides: only the configuration snapshot of the current session is modified—the agent itself is never changed, and multiple sessions can reuse the same agent with different customizations. The object fields are:
| Field | Required | Type | Description |
|---|---|---|---|
type | No | string | agent (reference only) or agent_with_overrides (reference with overrides). When carrying override fields, agent_with_overrides must be set explicitly; otherwise invalid_parameter is returned |
id | Yes | string | Agent ID |
version | No | integer | Agent version to pin; the current latest version is used when omitted. Returns not_found if the version does not exist |
system | No | string / null | Overrides the system prompt. Inherits the agent's source configuration when omitted; an empty string explicitly uses an empty prompt |
tools | No | array / null | Overrides the tool configuration; same structure as tools in Create Agent |
mcp_servers | No | array / null | Overrides the mounted MCP server list; same structure as mcp_servers in Create Agent |
skills | No | array / null | Overrides the mounted skill list; same structure as skills in Create Agent |
| Value | Effect |
|---|---|
| Omitted | Inherit the agent's source configuration |
null | Do not establish an override; inherit the source configuration |
[] (array fields) | Explicitly override to empty |
"" (only for system) | Explicitly use an empty prompt |
Session-level MCP request headers
mcp_configs injects custom headers into every request to the specified MCP servers, commonly used to pass tenant IDs or auth tokens. Each item contains mcp_server_name (MCP server name) and headers (key-value pairs where both key and value are strings). Passing a non-existent MCP server name does not raise an error; the configuration simply has no effect.
Full request examples for creation and update:
Response example
The session details embed a full agent snapshot.
Response fields
| Field | Type | Description |
|---|---|---|
id | string | Session ID, format sesn_<ULID> |
type | string | Fixed as session |
status | string | Session status: idle / running / terminated. Newly created sessions are idle |
agent | object | Full agent configuration snapshot, including id/version/name/model/system/tools, etc.; session-level overrides are merged into the snapshot |
environment_id | string | The bound environment ID |
resources | array | Mounted resource list. File items contain id (resource ID), type, file_id (internal copy ID), and mount_path (full path with prefix); memory store items contain id, type, file_id (always null), memory_store_id, name / description (store metadata), access, instructions, and mount_path (server-generated, e.g. /mnt/memory/<name>) |
title / metadata | string / object | Same as request body |
archived_at | string | null | Archive time; null when not archived |
created_at / updated_at | string | Creation/last update time, ISO 8601 |
request_id | string | Unique identifier for this request |
environment_variables | object | Environment variables injected into the session runtime as string key-value pairs; sandbox code can read them directly by name |
mcp_configs; query it via Get Session.
Configuration lock
A full snapshot of the agent's latest version is captured at session creation (embedded in the agent field of the session details). Subsequent edits to the agent only affect new sessions; existing sessions continue using the configuration from the snapshot. Session-level configuration is currently API-only; sessions created in the console are read-only snapshots. Session-level configuration can be modified after creation—see Update Session.