更新 Session

POST /api/v1/cloud/sessions/{session_id} 本接口用于更新一个已经创建的 Session。它既可以修改 title、metadata、environment_variables 等 Session 顶层属性，也可以通过 agent 对象动态修改该 Session 使用的模型、系统提示词、Tools、MCP servers、Skill bindings 等运行配置。省略的字段保持不变。

更新 Agent 或发布新的 Agent version，不会自动改变已经创建的 Session。Session 在创建时会固定一份运行配置快照。Skill binding 如果钉住了具体数字版本，发布新的 Skill version 后也会继续使用原版本。如需让已有 Session 应用这些变更，必须对该 Session 显式调用本接口并提交相应的 agent 字段。

路径参数

参数	类型	说明
`session_id`	string	以 `sess_` 为前缀的 Session ID

请求头

请求头	必填	说明
`Authorization`	是	`Bearer $QODER_ACCESS_TOKEN`
`Content-Type`	是	`application/json`
`x-qoder-beta`	更新 Beta Agent 字段时	更新 `agent.model`、`agent.system`、`agent.skills`、`agent.name` 或 `agent.description` 时，必须包含 `session-agent-patch-2026-07-21`
`x-qoder-beta`	使用 Browser Use 时	当 `agent.tools` 中配置了 `browser_toolset_20260714` 时，必须包含 `browser-use-2026-07-14`。详见 Browser Use（Beta）

同时需要两个 Beta ID 时，通过同一个请求头以逗号分隔：

x-qoder-beta: session-agent-patch-2026-07-21, browser-use-2026-07-14

请求体

普通 Session 属性与 agent 运行配置可以在同一个请求中提交；组合更新会在同一笔加锁事务中整体成功或整体失败。

字段	类型	必填	说明
`budget`	object \| null	否	会话总预算（含模型和沙箱费用），如 `{"type":"limit","max_credit_cost":"100.00"}`。省略会保留原设置；`null` 取消上限。详见 Session budget
`title`	string \| null	否	新标题；传 `null` 表示清空
`metadata`	object \| null	否	Metadata patch。对象中值为 `null` 的 key 会被删除；顶层 `null` 为 no-op
`environment_variables`	object \| null	否	整体替换 Session 显式配置的环境变量。未提交的 key 会被移除；`{}` 或 `null` 清空 Session 显式值。已有 Vault 中的环境变量凭证会重新合并，显式提交的 Session 值优先。校验规则与创建 Session相同
`agent`	object	否	动态更新当前 Session 内嵌的运行配置快照；对象中至少包含一个下文支持的字段

更新普通 Session 属性

Session 更新不使用 version 字段。并发 Metadata patch 基于加锁后的最新值合并；并发更新 title 或 environment_variables 时采用 last-write-wins 语义。

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e3bb1e8c171fd9abbb1477ffb84cc" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New title",
    "metadata": {
      "priority": "high",
      "old_key": null
    },
    "environment_variables": {
      "LOG_LEVEL": "debug"
    }
  }'

动态更新运行配置

虽然请求体使用 agent 对象，但操作范围包括该快照内所有受支持的 Session 运行配置，例如 skills。本接口更新的是当前 Session 的具体配置字段，不是把 Session 切换到某个 Agent ID 或 version。请勿提交 agent.id 或 agent.version。

更新 Agent/配置 ──> Agent version N+1 ──╳──> 已有 Session 快照 N
发布 Skill S+1 ─────────────────────────╳──> 钉住 Skill S 的 binding
                                                   │
POST /sessions/{session_id}，提交 agent 字段 ──────┘
      │
      └──> 更新运行配置快照，供后续 turn 使用

应用新发布的 Agent 配置

更新源 Agent，发布新的 Agent version。
获取目标 Agent version，读取该 version 的配置。
只把下文支持的字段复制到 agent patch 对象中。不要直接复制完整 Agent 响应，因为其中的 id、type、version、metadata 和 multiagent 在本接口中不可用。
对每个需要使用新配置的已有 Session，分别调用一次本接口。
确认响应中内嵌的 agent 已更新，再开始下一个 turn。

使用更新后 Agent 新建的 Session 会正常固定新的 Agent version；只有更新前已经存在的 Session 需要显式动态更新。

Skill version 的生效规则

skills[].version 为数字时，会钉住该 Skill version。发布更新的 Skill version 不会影响已有 Session；需要通过 agent.skills 提交新的数字版本，才能让 Session 前移。
省略 version 或传 "latest" 时，sandbox preparation 会动态解析最新 Skill version。仅仅为了更新 Skill 内容时，这种 binding 不需要更新 Session。
修改 Skill binding 列表本身，例如新增、移除或替换 Skill，始终需要对已有 Session 显式提交 agent.skills。

动态更新会形成一份可能不同于已发布 Agent 和 Skill version 的 Session 局部运行快照，但不会推进内嵌的 agent.version。判断更新是否生效时，请检查 Session 响应中的具体配置字段，不要依赖该值。

`agent` 中可更新的字段

字段	类型	Beta 请求头	语义
`model`	string \| Agent model	`session-agent-patch-2026-07-21`	在调用方可用模型目录中完成校验后，替换模型配置
`system`	string	`session-agent-patch-2026-07-21`	替换系统提示词
`tools`	Agent tool 数组	不需要；Browser Use 除外	整体替换工具配置，最多 128 项
`mcp_servers`	MCP server 数组	不需要	整体替换 MCP server 列表，最多 20 项
`skills`	Skill binding 数组	`session-agent-patch-2026-07-21`	整体替换 Skill 绑定列表，最多 20 项
`name`	string	`session-agent-patch-2026-07-21`	替换内嵌 Agent 快照中的名称
`description`	string	`session-agent-patch-2026-07-21`	替换内嵌 Agent 快照中的描述

以下 Agent 字段不能通过本接口更新：

字段	行为
`id`、`version`、`type`	作为未知字段被拒绝；本接口不会通过 Agent 引用重新固定 Session
`multiagent`	被拒绝；coordinator roster 不能动态修改
Agent `metadata`	被拒绝；如需修改 Session 级 `metadata`，请使用请求体顶层的 `metadata` 字段
其他 Agent 字段	直接拒绝，不会静默忽略

动态运行配置的更新语义

省略的 agent 字段保持原值。
tools、mcp_servers 和 skills 是整体替换。需要保留的条目必须全部提交；传 [] 可清空对应字段。
同时修改 tools 和 mcp_servers 时，应在同一请求中提交两个完整数组。每个 mcp_toolset 都必须引用最终 mcp_servers 列表中的名称。
修改 mcp_servers，或者在 Session 已有 MCP server 时修改 tools，都会重新执行 MCP discovery，并刷新冻结在 Session 快照中的工具。
单个 MCP server discovery 失败不会导致更新失败：接口仍返回 200 并发出 session.error 事件。请求配置不合法或快照/冻结过程发生内部错误时，更新会失败。
动态运行配置更新不使用乐观并发控制；并发成功的更新采用 last-write-wins 语义。
已归档或已终止的 Session 不能动态更新运行配置。

生效时机

更新后的 Agent 快照会写入 Session 及其 coordinator thread，后续 turn 使用新快照。更新前已经派发的 turn 可能继续使用旧配置；如果需要清晰的 turn 边界，请等待 Session 进入 idle 后再更新。

示例：应用新的模型、提示词和 Skill 配置

由于 skills 是整体替换，必须提交该 Session 需要保留的全部 Skill bindings。

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e3bb1e8c171fd9abbb1477ffb84cc" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-qoder-beta: session-agent-patch-2026-07-21" \
  -d '{
    "agent": {
      "model": {
        "id": "ultimate",
        "effort": "high",
        "context_window": 200000
      },
      "system": "Use the latest review policy and cite evidence for every conclusion.",
      "skills": [
        {
          "type": "custom",
          "skill_id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
          "version": "1759264410332875"
        }
      ]
    }
  }'

示例：替换 Tools 和 MCP servers

tools 和 mcp_servers 不需要 Session Agent Patch Beta ID。两个数组都是完整替换。

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e3bb1e8c171fd9abbb1477ffb84cc" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "tools": [
        {
          "type": "mcp_toolset",
          "mcp_server_name": "docs"
        }
      ],
      "mcp_servers": [
        {
          "name": "docs",
          "type": "url",
          "url": "https://mcp.example.com/mcp"
        }
      ]
    }
  }'

响应与事件

HTTP 200 OK 返回更新后的 Session 对象。动态运行配置更新既不会改变源 Agent 的 version，也不会推进 Session 快照内嵌的 agent.version。更新成功后会发出 session.updated：事件固定包含 id、type 和 processed_at，并根据更新内容选择性包含 title、metadata 或更新后的完整 agent 快照。事件不会包含环境变量值；如果请求只修改 environment_variables，事件只包含固定字段。完整事件结构参见 Session 数据结构。如果单个 MCP server discovery 失败，服务端还会发出 session.error，但会保留本次成功更新。

错误码

HTTP	类型	触发条件
400	`invalid_request_error`	请求体格式错误、包含未知字段或属性值不合法
400	`invalid_request_error`	`agent` 包含不支持的字段，或模型、工具、MCP server、Skill、跨字段配置不合法
400	`invalid_request_error`	提交 Beta Agent 字段时未携带 `session-agent-patch-2026-07-21`
400	`invalid_request_error`	提交的 `agent.tools` 包含 `browser_toolset_20260714`，但未携带 Browser Use Beta ID
400	`invalid_request_error`	Session 已归档或终止，且请求动态更新运行配置
401	`authentication_error`	PAT 或 SAT 无效或过期
404	`not_found_error`	Session 不存在，或普通属性更新的目标 Session 已归档
409	`invalid_request_error`	更新提交时 Session 被并发归档
500	`api_error`	无法安全解析已有 Vault 中的环境变量凭证
503	`feature_not_available`	Browser Use 暂时不可用
503	`api_error`	模型目录或其他必要依赖暂时不可用

完整错误信封格式参见错误处理。

启动 Session

让 Agent 在环境中以有状态对话的方式运行。

​路径参数

​请求头

​请求体

​更新普通 Session 属性

​动态更新运行配置

​应用新发布的 Agent 配置

​Skill version 的生效规则

​agent 中可更新的字段

​动态运行配置的更新语义

​生效时机

​示例：应用新的模型、提示词和 Skill 配置

​示例：替换 Tools 和 MCP servers

​响应与事件

​错误码

​相关

启动 Session

路径参数

请求头

请求体

更新普通 Session 属性

动态更新运行配置

应用新发布的 Agent 配置

Skill version 的生效规则

`agent` 中可更新的字段

动态运行配置的更新语义

生效时机

示例：应用新的模型、提示词和 Skill 配置

示例：替换 Tools 和 MCP servers

响应与事件

错误码

相关