千问办公企业旗舰版开发者文档:查询会话状态。
认证方式见APP开发者文档 → 认证接入。
媒体类型:
创建会话绑定当前IAM用户;资源读取与变更按用户归属校验。写入发生超时或响应丢失时,不应假定服务端未接纳并盲目重复请求。
- 模块:会话服务(session)
- 接口:GET
/api/openapi/app/v1/sessions/{session_id}
请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| session_id | path | string | 是 | 创建会话接口返回的会话 ID。 |
响应
| HTTP | 说明 |
|---|---|
| 200 | 请求成功 |
| default | 错误响应。按 code 判断具体错误,不能仅依赖 HTTP 状态码,多种错误可能共用状态码。 |
application/json。
响应200 SessionDetail
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| children | array<ChildRef> | 是 | 最多 15 项 | 此会话创建的子会话,最多 15 个;没有时为空数组。每个子项也是独立会话,可按其 ID 查询详情。 |
| created_at | string | 是 | ISO 8601 时间字符串 | 会话创建时间,ISO 8601,含微秒和时区,例如 2026-08-24T09:15:04.123456+00:00。 |
| current_turn | TurnRef / null | 是 | — | 当前执行中的回合,没有时为 null。等待用户回答的回合也算执行中,因此 action_required 时可非 null。用 turn_id 关联 Prompt 响应、事件和回合详情。回合切换时它与 status 可能短暂不同步,判断是否有回合可取消时优先参考 current_turn;持续不一致需要排查。 |
| cursor | integer | 是 | format="int64" | 会话最新事件序号,可用于历史查询。0 表示没有可用游标,可能尚无事件或本次读取失败;此时保留已有位置,不用 0 覆盖。 |
| end_reason | string / null | 是 | — | 会话结束原因,未结束时为 null,仅 terminated 时设置。开放枚举,未知值按异常结束处理。 |
| ended_at | string / null | 是 | ISO 8601 时间字符串 | 会话结束时间;仍存活时为 null。ISO 8601,格式与 created_at 相同。 |
| error | SessionError / null | 是 | — | 结构化失败信息,异常结束时返回;无失败时为 null。 |
| mode | string | 是 | — | 会话使用的能力档位。开放枚举,可用值通过运行档位列表查询。 |
| multi_agent | MultiAgentConfig | 是 | — | 此会话的子 Agent 配置。 |
| name | string | 是 | — | 会话显示名称,未指定时从首条 Prompt 生成。 |
| parent_session_id | string / null | 是 | — | 创建此会话的父会话 ID;顶层会话为 null。 |
| pending_action | PendingAction / null | 是 | — | 等待用户处理的问题;仅 action_required 状态下非 null。包含完整问题和提交回答所需的 tool_call_id。 |
| session_id | string | 是 | — | 创建接口返回的会话 ID。 |
| status | string | 是 | — | 当前会话状态,以此字段判断生命周期状态。 |
| updated_at | string | 是 | ISO 8601 时间字符串 | 会话记录最近更新时间,ISO 8601,格式与 created_at 相同。 |
响应200 ChildRef
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| name | string | 是 | — | 子会话显示名称。 |
| session_id | string | 是 | — | 子会话 ID,可用于查询完整详情。 |
| status | string | 是 | — | 子会话当前状态。 |
响应200 MultiAgentConfig
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| child_mode | string | 否 | — | 指定子会话的能力档位;省略时继承当前会话档位。 |
| enabled | boolean / null | 是 | — | 是否允许 Agent 创建子会话。每个子会话使用独立运行环境,会增加计算资源消耗;已创建的子会话列在会话详情的 children 中。 |
TurnRef
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| started_at | string | 是 | 回合开始时间,ISO 8601,含微秒和时区。尚未开始的排队 Prompt 不在此返回。 |
| turn_id | string | 是 | 当前回合 ID,用于查询回合详情及关联事件。 |
SessionError
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| category | string | 否 | 错误分类:quota、auth、permission、rate_limit、model_unavailable、timeout、content_rejected、input_too_large、input_invalid、limit_reached、service_error、unknown;开放枚举。 |
| code | string | 是 | 机器可识别的错误码;未知值按一般失败处理。 |
| message | string | 是 | 供展示和排查的错误文字,不作为程序分支条件。 |
| remedy | string | 否 | 建议处理方式:retry、retry_after_backoff、switch_model、new_session、modify_input、reauthenticate、top_up_quota、contact_admin、refresh、report。按此字段决定下一步;未知值不盲目重试。 |
| trace_id | string | 否 | 服务端请求追踪标识,用于故障排查。 |
PendingAction
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| asked_at | string | 是 | Agent 提问时间,ISO 8601,含微秒和时区。 |
| questions | array<Question> | 是 | 待展示的问题数组;answers 按相同顺序提交。 |
| tool_call_id | string | 是 | 提交问题回答时原样传回的工具调用标识。 |
Question
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| header | string | 否 | 可选的问题短标题。 |
| multi_select | boolean | 是 | 是否允许多选。每道题仍对应一个 answers 字符串;多选作为文本交给 Agent 解释,单选传选项 label。 |
| options | array<QuestionOption> | 否 | 可选项;省略或为空时允许自由文本回答。 |
| question | string | 是 | 问题正文。 |
QuestionOption
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| description | string | 否 | 选择此选项的补充说明。 |
| label | string | 是 | 选项标识兼展示文字;回答时原样提交。 |