根据 Session ID 返回会话状态、Agent 快照、环境摘要与 Token 用量。
接口
GET /agents/sessions/{session_id}
成功返回 200 和完整 Session 对象。
路径参数session_idstring (必选)Session ID,按不透明字符串使用本接口没有 Query 参数。session_id 格式错误、不存在、已归档或属于其他工作空间时返回 404。 | 请求示例 |
响应字段字段不齐时为null。 status=idle 或 HTTP 200 不充分证明上一轮 Turn 成功;需要结合 Turn 终态判断。usage 要求相关计数齐全,否则整个字段为 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_subagentsobject环境安全摘要;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插件信息,当前托管环境为 []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已解析的调用参数string / nullSession 级错误说明,与 Turn 的结构化 error 不同usage object / nullToken 用量。
属性 input_tokens integer输入 Token 数input_tokens_details object输入 Token 明细。
属性 cached_tokens integer命中缓存的输入 Token 数integer输出 Token 数output_tokens_details object输出 Token 明细。
属性 reasoning_tokens integer推理 Token 数integer总 Token 数object费用控制,仅历史记录带值时返回;创建和更新接口不接受写入。
属性 limit integer额度上限,单位为美分consumed integer / null已消耗额度,单位为美分 | 响应示例 |
错误码
业务错误返回 error 对象,包含 type、code、message 和 param。常见错误如下:
| HTTP 状态码 | 错误类型 / 错误码 | 解决方案 |
|---|---|---|
400 | invalid_request_error / invalid_request_error | 按路径参数格式传入有效值 |
401 | authentication_error / invalid_api_key | 在请求头携带有效的 Authorization: Bearer $DASHSCOPE_API_KEY |
404 | not_found_error / not_found_error | 使用当前工作空间中未归档且格式正确的 Session ID |
502 | server_error / agents_api_upstream_unavailable | 稍后重试;持续失败时提交工单并提供响应头中的 x-request-id |