跳转到主要内容
Session & Event

创建 Session

启动一个新会话

POST
/api/v1/agentstudio/sessions
cURL
curl --request POST \
  --url 'https://maas.qianwenaiapi.com/api/v1/agentstudio/sessions' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent": {
    "type": "agent_with_overrides",
    "id": "agent_xxx",
    "system": "你是本会话专用的数据分析助手。",
    "tools": [],
    "mcp_servers": [],
    "skills": []
  },
  "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"
  },
  "mcp_configs": [
    {
      "mcp_server_name": "weather",
      "headers": {
        "X-Tenant-Id": "tenant-demo"
      }
    }
  ]
}
'
{
  "id": "sesn_xxx",
  "type": "session",
  "status": "idle",
  "agent": {
    "id": "agent_xxx",
    "type": "agent",
    "version": 1,
    "name": "data-analyst",
    "description": null,
    "model": {
      "id": "qwen3.8-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"
  }
}

鉴权

string
header
必填

DashScope API Key

请求体

application/json
object
必填

绑定的智能体引用对象。可仅引用智能体,也可锁定版本并按需建立会话级覆盖(system / tools / mcp_servers / skills),覆盖仅作用于本会话,不改动智能体本身

string
必填

绑定的运行环境 ID。环境配置预装包时创建后可能需要预热,准备中的环境不可被会话绑定(返回 invalid_parameter),需等待预热完成

string

会话标题,便于在列表中辨识

object[]

创建时挂载的文件列表。文件挂载后以副本形式进入会话沙箱

string[]

Vault ID 列表。将指定 Vault 中的 Credential 注入会话运行环境,使智能体可访问对应密钥

object

业务自定义键值,不影响模型行为

object

会话运行时注入的环境变量,字符串键值对,沙箱代码中可直接按名读取

object[]

会话级 MCP 请求头,独立于 agent 字段。对指定 MCP Server 的全部出网请求注入自定义 Header;省略时为空数组。传入不存在的 MCP Server 名称不报错,运行时该配置不生效。接入方法与示例见自定义 MCP 与 Skills

响应

200-application/json
string

会话 ID,格式 sesn_<ULID>

string

固定为 session

enum<string>

会话状态:idle / running / terminated。新建会话为 idle

idle,running,terminated
object

智能体配置完整快照,含 id/version/name/model/system/tools 等;会话级覆盖已并入快照。本响应不含 mcp_configs,可通过获取 Session 接口查询

string

绑定的运行环境 ID

string

会话标题

object[]

挂载的文件列表。文件为副本挂载

object

业务自定义键值

string | null

归档时间,未归档时为 null

string

创建时间,ISO 8601

string

最近更新时间,ISO 8601

string

本次请求的唯一标识

object

会话运行时注入的环境变量