更新 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_id | string | 是 | Session ID。 |
请求体参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| title | string | 否 | 新的 Session 标题。 |
| metadata | object | 否 | metadata merge patch;传入的 key 覆盖已有 key,未出现的 key 保留。 |
| budget | object | null | 否 | 省略保留原预算,null 清除上限,对象整体替换累计消费上限。可与 config 同时传入,格式见 Session budget。 |
| budget.type | string | budget 为对象时必填 | 固定为 limit。 |
| budget.max_credit_cost | string | budget 为对象时必填 | 正十进制金额字符串,范围 0.01–999999999999.99,最多两位小数;新上限必须严格大于已消费的累计 Credit。 |
| config | object | 否 | Session 配置更新,只允许包含 environment_variables、model 和 multiagent。null 不合法;省略或 {} 不修改现有配置。 |
| config.environment_variables | object<string, string>(推荐) | 否 | Session 环境变量;新接入请将每个 value 都作为字符串传入。传入的 map 整组替换已有的 Session 级环境变量,替换后在 Template + Identity Config 编译结果基础上追加合并,同名变量覆盖基础层的值。 |
| config.model | string | object | null | 否 | 非 null 值整值替换 Session 模型覆盖;null 删除覆盖并恢复继承;省略保持当前模型覆盖。 |
| config.multiagent | object | 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 的模型格式一致。可用模型和支持的选项请查询列出模型。
| 对象字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 非空模型 ID,取自列出模型返回的 id。 |
| effort | string | 否 | Reasoning effort 等级:none、low、medium、high、xhigh、max;实际支持的等级以模型的 efforts 为准,省略时使用模型默认值。 |
| speed | string | 否 | 推理速度:standard、high;省略时使用 standard。实际支持的速度以模型的 speed 数组为准。 |
| context_window | integer | 否 | 上下文窗口的 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 条目。
| 对象字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 固定为 coordinator。 |
| agents | array | 是 | 非空名单,最多 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。 |
version,Forward 会统一使用 latest 并固定本次更新时的版本,传入的 version 不用于选择历史版本。
示例请求
示例响应
HTTP 200 OK
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| 返回值 | object | 更新后的 Session 对象。 |
| config.model | string | object | 更新后保存的 Session 模型覆盖值,保留 string / object 形态;删除覆盖后省略。 |
| config.multiagent | object | null | 已保存的 Session 名单覆盖,保留提交的 Forward 引用形态;显式清空时返回 null,未设置覆盖时省略。该字段不返回运行时固定的具体子 Agent 版本。 |
错误
| HTTP | Type | Code | 触发条件 |
|---|---|---|---|
| 503 | api_error | session_materialization_busy | 更新 config.environment_variables、config.model 或 config.multiagent 时需要刷新会话配置,但运行时返回版本或状态冲突。响应包含 Retry-After: 1;等待当前 Turn 完成后重试。 |
| 400 | invalid_request_error | invalid_request | 更新请求体不合法,包括 config.model 为 {}、空 ID、非法类型或参数,config.multiagent 结构、名单数量或条目不合法,以及不支持的配置字段。 |
| 400 | invalid_request_error | invalid_request_body | 请求体 JSON 不合法,或 config、config.environment_variables 不合法。 |
| 400 | invalid_request_error | - | 引用的子 Template 不存在、已归档、不可访问或尚不可用于会话。 |
| 400 | invalid_request_error | - | budget 的类型、金额或字段不合法。 |
| 400 | invalid_request_error | - | 新预算上限小于或等于已消费的累计 Credit。 |
| 404 | not_found_error | session_not_found | Session 不存在。 |
| 409 | invalid_request_error | session_archived | Session 已归档。 |
| 409 | conflict_error | - | 会话配置快照缺失,无法单独更新 config.multiagent;需先完成普通配置更新。 |
| 401 | authentication_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。