Create Session
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
curl -X POST "$AGENTSTUDIO_URL/sessions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {"type": "agent", "id": "agent_xxx"},
"environment_id": "env_xxx",
"title": "Q3 销售数据分析",
"resources": [
{"type": "file", "file_id": "file_xxx", "mount_path": "/uploads/workspace/data.csv"}
],
"vault_ids": ["vlt_xxx"],
"metadata": {"biz_ticket_id": "1234"},
"environment_variables": {"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"}
}'
session = client.sessions.create(
agent={"type": "agent", "id": "agent_xxx"},
environment_id="env_xxx",
title="Q3 销售数据分析",
resources=[
{"type": "file", "file_id": "file_xxx", "mount_path": "/uploads/workspace/data.csv"},
],
vault_ids=["vlt_xxx"],
metadata={"biz_ticket_id": "1234"},
environment_variables={"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"},
)
print(session.id, session.status)
Map<String, String> metadata = new HashMap<>();
metadata.put("biz_ticket_id", "1234");
Map<String, String> environmentVariables = new HashMap<>();
environmentVariables.put("API_BASE_URL", "https://api.example.com");
environmentVariables.put("LOG_LEVEL", "info");
Session session = client.sessions().create(SessionCreateParam.builder()
.agent(SessionAgent.ofOverride(Map.of("type", "agent", "id", "agent_xxx")))
.environmentId("env_xxx")
.title("Q3 销售数据分析")
.resources(List.of(SessionResource.builder()
.type("file")
.fileId("file_xxx")
.mountPath("/uploads/workspace/data.csv")
.build()))
.vaultIds(List.of("vlt_xxx"))
.metadata(metadata)
.environmentVariables(environmentVariables)
.build());
System.out.println(session.getId() + " " + session.getStatus());
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 |
Semantics of override field values (consistent between createSession and Update Session):
| 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. For the per-session workflow and examples, see Custom MCP and Skills.
Full request examples for creation and update:
curl -X POST "$AGENTSTUDIO_URL/sessions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"type": "agent_with_overrides",
"id": "agent_xxx",
"system": "你是本会话专用的数据核对助手,只输出核对结论。"
},
"environment_id": "env_xxx",
"mcp_configs": [
{"mcp_server_name": "crm", "headers": {"X-Tenant-Id": "tenant-demo"}}
]
}'
session = client.sessions.create(
agent={"type": "agent_with_overrides", "id": "agent_xxx",
"system": "你是本会话专用的数据核对助手,只输出核对结论。"},
environment_id="env_xxx",
mcp_configs=[{"mcp_server_name": "crm", "headers": {"X-Tenant-Id": "tenant-demo"}}],
)
Map<String, Object> agentOverride = Map.of(
"type", "agent_with_overrides",
"id", "agent_xxx",
"system", "你是本会话专用的数据核对助手,只输出核对结论。");
Map<String, String> headers = Map.of("X-Tenant-Id", "tenant-demo");
Session session = client.sessions().create(SessionCreateParam.builder()
.agent(agentOverride)
.environmentId("env_xxx")
.mcpConfigs(List.of(Map.of(
"mcp_server_name", "crm",
"headers", headers)))
.build());
Response example
The session details embed a full agent snapshot.
{
"id": "sesn_xxx",
"type": "session",
"status": "idle",
"agent": {
"id": "agent_xxx",
"type": "agent",
"version": 1,
"name": "data-analyst",
"description": null,
"model": {"id": "qwen3.7-max"},
"system": "你是数据分析专家,使用 pandas 处理 CSV 文件。",
"tools": []
},
"environment_id": "env_xxx",
"title": "Q3 销售数据分析",
"resources": [
{
"id": "sesrsc_xxx",
"type": "file",
"file_id": "file_xxx",
"mount_path": "/mnt/session/uploads/workspace/data.csv",
"created_at": "2026-05-28T08:23:11Z",
"updated_at": "2026-05-28T08:23:11Z"
}
],
"metadata": {"biz_ticket_id": "1234"},
"archived_at": null,
"created_at": "2026-05-28T08:23:11Z",
"updated_at": "2026-05-28T08:23:11Z",
"request_id": "xxx",
"environment_variables": {"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"}
}
The response is a Session object with the following fields:
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 |
This response does not contain 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.