Create Session

Updated at:

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

FieldRequiredTypeDescription
agentYesobjectThe 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_idYesstringThe 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
titleNostringSession title for easy identification in lists
resourcesNoarrayResources 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_idsNoarray of stringVault ID list. Injects credentials from the specified vaults into the session runtime environment, allowing the agent to access the corresponding secrets
metadataNoobjectCustom key-value pairs for business use; does not affect model behavior
environment_variablesNoobjectEnvironment variables injected into the session runtime as string key-value pairs; sandbox code can read them directly by name
mcp_configsNoarraySession-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:

FieldRequiredTypeDescription
typeNostringagent (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
idYesstringAgent ID
versionNointegerAgent version to pin; the current latest version is used when omitted. Returns not_found if the version does not exist
systemNostring / nullOverrides the system prompt. Inherits the agent's source configuration when omitted; an empty string explicitly uses an empty prompt
toolsNoarray / nullOverrides the tool configuration; same structure as tools in Create Agent
mcp_serversNoarray / nullOverrides the mounted MCP server list; same structure as mcp_servers in Create Agent
skillsNoarray / nullOverrides the mounted skill list; same structure as skills in Create Agent

Semantics of override field values (consistent between createSession and Update Session):

ValueEffect
OmittedInherit the agent's source configuration
nullDo 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

FieldTypeDescription
idstringSession ID, format sesn_&lt;ULID&gt;
typestringFixed as session
statusstringSession status: idle / running / terminated. Newly created sessions are idle
agentobjectFull agent configuration snapshot, including id/version/name/model/system/tools, etc.; session-level overrides are merged into the snapshot
environment_idstringThe bound environment ID
resourcesarrayMounted 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 / metadatastring / objectSame as request body
archived_atstring | nullArchive time; null when not archived
created_at / updated_atstringCreation/last update time, ISO 8601
request_idstringUnique identifier for this request
environment_variablesobjectEnvironment 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.