Skip to main content

更新 Session

更新 Session 的 metadata、模型、推理强度与服务档位,只影响后续 Turn。

接口

POST /agents/sessions/{session_id} 成功返回 200 和更新后的完整 Session。更新只支持 metadata、agent.model 和 agent.reasoning.effort。 更新只影响后续 Turn,不改变正在执行的 Turn,也不回写已保存的 Agent。并发更新冲突时返回 409 conflict_error,重新读取后重试。

请求体

metadata object / null (可选)元数据,整体替换,缺失保持原值,null 或 {} 清空。最多 16 项,key 非空且不超过 64 字符,value 为字符串且不超过 512 字符agent object (可选)会话级设置,缺失保持原值,null 拒绝,{} 合法但不修改设置。未知字段拒绝
model string (可选)后续 Turn 使用的模型,缺失保持原值,null 或全空白拒绝。更新入口上限 1,048,576 字符,模型变更必须属于当前工作空间可用的模型reasoning object (可选)只能包含 effort,不能传 summary,缺失保持原值,null 拒绝
effort string / null (可选)推理强度,none、minimal、low、medium、high、xhigh、max、ultra;null 重置为模型默认值
metadata 和 agent 至少出现一个。空请求体、JSON null 或整个请求体为 {} 时返回 400。agent: {} 本身合法,但不会修改任何设置。更新先校验设置,再读取和合并资源;非法设置与资源不存在同时发生时,可能先返回 400。

请求示例

curl -sS -X POST "$BASE_URL/agents/sessions/sess_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"source": "updated"},
    "agent": {
      "model": "qwen3.8-max",
      "reasoning": {"effort": "medium"}
    }
  }'

响应字段

返回更新后的完整 Session 对象。 字段不齐时为 null。id stringSession ID,继续对话时复用object stringSession 对象类型,固定为 agent.sessioncreated_at integer创建时间,Unix 秒last_active_at integer最近活动时间,Unix 秒;不是版本号或锁status stringSession 状态:idle、in_progress、requires_action、failedagent object当前生效的 Agent 快照。
id stringAgent ID;内联配置生成的是会话快照 ID,不是可复用的已保存 Agent,不能通过 Agent GET 查询model string模型 IDinstructions string / null自定义指令name string / null展示名称reasoning object / null推理配置,包含 effort、summarytext object / null文本输出配置;包含 format 和 verbositytools array工具配置multi_agent object / null子 Agent 配置;包含 enabled、max_concurrent_subagents
environment object环境安全摘要;type=none 时只有 type。
type string环境类型;none 或 openai_hostedid string环境 ID,无权威来源时省略status string环境状态:无权威来源时省略environment_template_id string环境模板 ID;无权威来源时省略workspace_directory string工作目录;无权威来源时省略error string / null环境错误说明;无权威来源时省略desktop object / null桌面配置;包含 enabledcapability_directories array<string> / null能力发现目录network object / null网络策略;包含 access、allowed_domainspackages object / null包列表;包含 npm、python、systemfiles array环境文件安全元数据skills arraySkill 安全元数据plugins array插件信息,当前托管环境为 []
metadata objectSession 元数据,空值为 {}vault_ids array<string>创建时记录的 Vault ID,不代表挂载已完成required_actions array需要客户端处理的 Function 调用;空时为 []。
type stringItem 类型,固定为 function_callturn_id string公开 Turn IDcall_id stringFunction 调用 IDname string函数名arguments object已解析的调用参数
error string / nullSession 级错误说明,与 Turn 的结构化 error 不同usage object / nullToken 用量。
input_tokens integer输入 Token 数input_tokens_details object输入 Token 明细。
cached_tokens integer命中缓存的输入 Token 数
output_tokens integer输出 Token 数output_tokens_details object输出 Token 明细。
reasoning_tokens integer推理 Token 数
total_tokens integer总 Token 数
spend_control object费用控制,仅历史记录带值时返回;创建和更新接口不接受写入。
limit integer额度上限,单位为美分consumed integer / null已消耗额度,单位为美分

响应示例

{
  "id": "sess_xxx",
  "object": "agent.session",
  "created_at": 1794118835,
  "last_active_at": 1794119300,
  "status": "idle",
  "agent": {
    "id": "agent_xxx",
    "model": "qwen3.8-max",
    "instructions": "回答简洁。",
    "reasoning": {"effort": "medium", "summary": "auto"},
    "text": {"format": {"type": "text"}, "verbosity": "medium"},
    "tools": [],
    "multi_agent": {"enabled": false, "max_concurrent_subagents": null},
    "name": null
  },
  "environment": {"type": "none"},
  "metadata": {"source": "updated"},
  "required_actions": [],
  "vault_ids": [],
  "error": null,
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 8,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 20
  }
}

错误码

业务错误返回 error 对象,包含 type、code、message 和 param。常见错误如下:
HTTP 状态码错误类型 / 错误码解决方案
400invalid_request_error / invalid_request_error至少传入 metadata 或 agent 之一,并发送合法 JSON 对象
400invalid_request_error / unknown_parameter、invalid_type、invalid_value删除未知字段,按字段说明修正类型和枚举值
400invalid_request_error / object_above_max_properties、empty_property_name、property_name_above_max_length、string_above_max_length按字段说明缩短 metadata 或字符串字段
401authentication_error / invalid_api_key在请求头携带有效的 Authorization: Bearer $DASHSCOPE_API_KEY
404not_found_error / not_found_error使用当前工作空间中未归档且格式正确的 Session ID
409conflict_error / conflict_error重新读取 Session 后重试
502server_error / agents_api_upstream_unavailable稍后重试;持续失败时提交工单并提供响应头中的 x-request-id