Skip to main content

更新 Session

更新 Forward Session 的标题、metadata、预算、环境变量、模型或子 Agent 配置。

POST /api/v1/forward/sessions/{session_id} config 支持更新 environment_variables、model 和 multiagent。模型和子 Agent 更新仅作用于本 Session,不修改 Template 或 Identity Config。

请求头

Header是否必填说明
Authorization是Bearer <PAT 或 SAT>
Content-Type是application/json
Idempotency-Key否有副作用请求可选的幂等键。

路径参数

参数类型是否必填说明
session_idstring是Session ID。

请求体参数

参数类型是否必填说明
titlestring否新的 Session 标题。
metadataobject否metadata merge patch;传入的 key 覆盖已有 key,未出现的 key 保留。
budgetobject | null否省略保留原预算,null 清除上限,对象整体替换累计消费上限。可与 config 同时传入,格式见 Session budget。
budget.typestringbudget 为对象时必填固定为 limit。
budget.max_credit_coststringbudget 为对象时必填正十进制金额字符串,范围 0.01–999999999999.99,最多两位小数;新上限必须严格大于已消费的累计 Credit。
configobject否Session 配置更新,只允许包含 environment_variables、model 和 multiagent。null 不合法;省略或 {} 不修改现有配置。
config.environment_variablesobject<string, string>(推荐)否Session 环境变量;新接入请将每个 value 都作为字符串传入。传入的 map 整组替换已有的 Session 级环境变量,替换后在 Template + Identity Config 编译结果基础上追加合并,同名变量覆盖基础层的值。
config.modelstring | object | null否非 null 值整值替换 Session 模型覆盖;null 删除覆盖并恢复继承;省略保持当前模型覆盖。
config.multiagentobject | null否整体替换并保存本 Session 的子 Agent 配置;重传相同名单会刷新子 Agent 版本;null 清空名单并保留空覆盖,省略则保持现有名单及已固定的版本。详见 config.multiagent。
config.environment_variables 更新语义:
  • 缺省或 config 为 {}:不修改环境变量。
  • 非空 object:整组替换 Session 级环境变量 map,不与旧值增量合并,未出现的旧 key 会被删除。
  • 空 object {}:清空 Session 级环境变量。
  • value 请使用字符串;object、array value 不合法。
  • 整组替换只作用于 Session 级这一层;更新后 Session 的运行时环境变量仍在 Template + Identity Config 编译结果基础上追加合并,同名变量以 Session 级的值覆盖。
  • 环境变量名称、保留字与容量限制由运行时校验,不合法时返回 400。

config.model

config.model 支持非空模型 ID 字符串(例如 "ultimate"),或包含模型 ID 和可选调优参数的对象,与 Template / Identity Config 的模型格式一致。可用模型和支持的选项请查询列出模型。
对象字段类型是否必填说明
idstring是非空模型 ID,取自列出模型返回的 id。
effortstring否Reasoning effort 等级:none、low、medium、high、xhigh、max;实际支持的等级以模型的 efforts 为准,省略时使用模型默认值。
speedstring否推理速度:standard、high;省略时使用 standard。实际支持的速度以模型的 speed 数组为准。
context_windowinteger否上下文窗口的 token 数,必须为正整数;请从模型的 available_context_windows 中选择,省略时使用模型默认窗口。
模型与选项组合是否可用,以列出模型的能力和运行时校验结果为准。
  • 省略 config.model:保持当前配置。
  • 传入 string / object:整体替换模型配置,未提交的旧选项不保留,新配置用于后续模型调用。
  • 传入 null:删除 Session 模型覆盖,恢复继承当前 Template / Identity Config 的模型。
  • 传入 {}:返回 400;模型对象必须包含非空 id。
template.model 是模板摘要;Session 模型覆盖值请查看响应中的 config.model。

config.multiagent

config.multiagent 使用与 Template Multi-agent 配置相同的名单结构。每次更新都应提交完整名单,包括需要保留的普通 Agent、self 和 Advisor 条目。
对象字段类型是否必填说明
typestring是固定为 coordinator。
agentsarray是非空名单,最多 20 个普通 Agent 条目(含 self),另可包含 1 个 Advisor。
推荐使用 {"type":"agent","template_id":"tmpl_research"} 引用子 Template。被引用的 Template 必须存在、未归档且当前调用方有权访问。普通条目也支持 Template / CAS Agent ID 字符串、{"type":"agent","id":"agent_xxx"} 和 {"type":"self"};Advisor 使用 {"type":"advisor","model":"ultimate"},只接受 type、model 两个字段。
请求形态语义
省略 config.multiagent保持现有名单、Session 覆盖和已固定的子 Agent 版本。
提交完整multiagent配置整体替换本 Session 的名单,解析并固定当前最新子 Agent 版本;未包含的旧条目从名单中移除。
config.multiagent: null清空名单并保存本 Session 的空覆盖;后续 Template 更新不会恢复名单。null 不表示恢复继承。
{} 或空 agents 数组返回 400;清空名单应使用 null。
子 Agent 引用无需传 version,Forward 会统一使用 latest 并固定本次更新时的版本,传入的 version 不用于选择历史版本。

示例请求

curl -s -X POST 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Updated session title",
  "budget": {
    "type": "limit",
    "max_credit_cost": "100.00"
  },
  "metadata": {
    "source": "mobile",
    "biz_id": "ticket_123"
  },
  "config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 200000
    },
    "environment_variables": {
      "API_KEY": "sk-xxx",
      "REGION": "cn-hangzhou"
    }
  }
}'

示例响应

HTTP 200 OK
{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "Support assistant",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "Updated session title",
  "metadata": {
    "source": "mobile",
    "biz_id": "ticket_123"
  },
  "config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 200000
    },
    "environment_variables": {
      "API_KEY": "sk-xxx",
      "REGION": "cn-hangzhou"
    }
  },
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "total_credits": 12.7
  },
  "budget": {
    "type": "limit",
    "max_credit_cost": "100.00"
  },
  "outcome_evaluations": [],
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T12:00:00Z"
}

响应字段

字段类型说明
返回值object更新后的 Session 对象。
config.modelstring | object更新后保存的 Session 模型覆盖值,保留 string / object 形态;删除覆盖后省略。
config.multiagentobject | null已保存的 Session 名单覆盖,保留提交的 Forward 引用形态;显式清空时返回 null,未设置覆盖时省略。该字段不返回运行时固定的具体子 Agent 版本。

错误

HTTPTypeCode触发条件
503api_errorsession_materialization_busy更新 config.environment_variables、config.model 或 config.multiagent 时需要刷新会话配置,但运行时返回版本或状态冲突。响应包含 Retry-After: 1;等待当前 Turn 完成后重试。
400invalid_request_errorinvalid_request更新请求体不合法,包括 config.model 为 {}、空 ID、非法类型或参数,config.multiagent 结构、名单数量或条目不合法,以及不支持的配置字段。
400invalid_request_errorinvalid_request_body请求体 JSON 不合法,或 config、config.environment_variables 不合法。
400invalid_request_error-引用的子 Template 不存在、已归档、不可访问或尚不可用于会话。
400invalid_request_error-budget 的类型、金额或字段不合法。
400invalid_request_error-新预算上限小于或等于已消费的累计 Credit。
404not_found_errorsession_not_foundSession 不存在。
409invalid_request_errorsession_archivedSession 已归档。
409conflict_error-会话配置快照缺失,无法单独更新 config.multiagent;需先完成普通配置更新。
401authentication_error-PAT 或 SAT 无效或已过期。
预算校验错误不包含 error.code 或 error.param。预算校验失败时,本次请求中的标题、metadata 和配置更新均不生效。 预算与环境变量同时更新时,预算错误的 error.message 可能被脱敏为 Bad Request 或 cloud-agents-service rejected a request containing credentials。非法预算类型的错误文案也可能包含解码详情;客户端不应依赖具体文案或其中的内部类型名,应结合 HTTP 状态、error.type 和 request_id 排查。

备注

  • 仅更新标题或 metadata 不触发上述配置刷新。环境变量、模型或子 Agent 更新收到 session_materialization_busy 时,遵循 Retry-After 并等待当前 Turn 完成,再用相同请求体重试;原请求携带 Idempotency-Key 时沿用同一键。该临时拒绝不会被缓存为最终幂等响应;此规则仅适用于该错误码。
  • resources 是创建时配置,不能通过本接口修改;如需在会话进行中追加文件资源,请使用添加 Session 资源接口。
  • 同时更新预算和配置时,后续文件刷新或提交失败前,预算和模型等可能已经生效;请先获取 Session 确认状态,再决定是否重试。
  • 响应中的 config.environment_variables 反映更新后的结果。
  • 仅为兼容既有调用,非字符串标量 value 会规范化为字符串(null 为空字符串);新接入请使用字符串 value。

相关