更新会话 API：POST /sessions/{session_id}-大模型服务平台百炼(Model Studio)-阿里云帮助中心

修改会话的 title、metadata、environment_variables、vault_ids、会话级智能体配置与会话级 MCP 请求头。会话更新是唯一会触发 session.updated 事件的操作。

前提

已完成 Endpoint 与鉴权配置，详见API 总览与认证。

接口

POST /sessions/{session_id}

支持修改 title、metadata、environment_variables、vault_ids、会话级智能体配置（agent）与会话级 MCP 请求头（mcp_configs）。数组与对象字段整体替换，空值清空。会话更新是唯一会触发session.updated事件的操作。

请求体

字段	必填	类型	说明
`title`	否	string	会话标题。省略保持原值，`null` 不执行更新
`metadata`	否	object	业务自定义键值。整体替换；省略保持原值，`null` 不执行更新
`environment_variables`	否	object	会话运行时注入的环境变量，字符串键值对，沙箱代码中可直接按名读取。整体替换；空对象清空，省略保持原值
`vault_ids`	否	array of string	整体替换 Vault 绑定；空数组清空，省略保持原值
`agent`	否	object	会话级智能体配置 patch，只能携带 `system` / `tools` / `mcp_servers` / `skills` 覆盖字段，携带其他字段（如 `type` / `id` / `version` / `model`）返回 invalid_parameter。见会话级配置 patch
`mcp_configs`	否	array	整体替换会话级 MCP 请求头，结构与创建 Session一致；空数组清空，省略保持原值，`null` 非法

会话级配置 patch

agent patch 只修改本会话的配置快照，不生成智能体新版本。子字段取值语义（与创建 Session 的覆盖语义一致）：

取值	效果
省略	保留已有覆盖
`null`	删除该字段覆盖，重新继承智能体源配置
`[]`（数组字段）	明确覆盖为空
`""`（仅 `system`）	明确使用空提示词

请求示例

bash

curl -X POST "$AGENTSTUDIO_URL/sessions/sesn_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q3 销售复盘",
    "metadata": {"biz_ticket_id": "1234", "status": "done"},
    "environment_variables": {"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"},
    "agent": {
      "system": "你是本会话专用的项目分析助手。",
      "skills": []
    },
    "mcp_configs": [
      {"mcp_server_name": "crm", "headers": {"X-Tenant-Id": "tenant-demo"}}
    ]
  }'

python

session = client.sessions.update(
    "sesn_xxx",
    title="Q3 销售复盘",
    metadata={"biz_ticket_id": "1234", "status": "done"},
    environment_variables={"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"},
    agent={"system": "你是本会话专用的项目分析助手。", "skills": []},
    mcp_configs=[{"mcp_server_name": "crm", "headers": {"X-Tenant-Id": "tenant-demo"}}],
)

java

Map<String, String> metadata = new HashMap<>();
metadata.put("biz_ticket_id", "1234");
metadata.put("status", "done");

Map<String, String> environmentVariables = new HashMap<>();
environmentVariables.put("API_BASE_URL", "https://api.example.com");
environmentVariables.put("LOG_LEVEL", "info");

Map<String, Object> agentPatch = Map.of(
    "system", "你是本会话专用的项目分析助手。",
    "skills", List.of());
Map<String, String> headers = Map.of("X-Tenant-Id", "tenant-demo");

Session updated = client.sessions().update("sesn_xxx",
    SessionUpdateParam.builder()
        .title("Q3 销售复盘")
        .metadata(metadata)
        .environmentVariables(environmentVariables)
        .agent(agentPatch)
        .mcpConfigs(List.of(Map.of(
            "mcp_server_name", "crm",
            "headers", headers)))
        .build());

响应示例

返回更新后的会话详情：title / metadata 等覆盖后的新值、agent（覆盖已并入的完整快照）、mcp_configs、vault_ids、updated_at 与 request_id。

{
  "id": "sesn_xxx",
  "type": "session",
  "status": "idle",
  "title": "Q3 销售复盘",
  "metadata": {"biz_ticket_id": "1234", "status": "done"},
  "updated_at": "2026-05-28T09:30:00Z",
  "request_id": "xxx",
  "environment_variables": {"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"},
  "agent": {
    "id": "agent_xxx",
    "type": "agent",
    "version": 1,
    "name": "data-analyst",
    "system": "你是本会话专用的项目分析助手。",
    "tools": [],
    "mcp_servers": [],
    "skills": []
  },
  "vault_ids": ["vlt_xxx"],
  "mcp_configs": [{"mcp_server_name": "crm", "headers": {"X-Tenant-Id": "tenant-demo"}}]
}

响应字段

字段	类型	说明
`id`	string	会话 ID
`type`	string	固定为 `session`
`status`	string	当前会话状态（更新不改变状态）
`title` / `metadata`	string / object	请求体覆盖后的新值
`updated_at`	string	最近更新时间，ISO 8601
`request_id`	string	本次请求的唯一标识
`environment_variables`	object	会话运行时注入的环境变量，字符串键值对，沙箱代码中可直接按名读取
`agent`	object	更新后的智能体配置快照，会话级覆盖已并入。字段同获取 Session
`vault_ids`	array of string	更新后的 Vault 绑定
`mcp_configs`	array of object	更新后的会话级 MCP 请求头，每项含 `mcp_server_name` 与 `headers`