Create Session API: POST /sessions-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

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.

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	string	The bound agent ID. The session locks a snapshot of the agent's current latest version
`environment_id`	Yes	string	The bound environment ID
`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

Request example

bash

curl -X POST "$AGENTSTUDIO_URL/sessions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "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"}
  }'

python

session = client.sessions.create(
    agent="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)

java

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()
    .agentId("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());

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-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 (locked at creation), including `id`/`version`/`name`/`model`/`system`/`tools`, etc.
`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

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.