千问办公企业旗舰版开发者文档:查询执行回合。
认证方式见APP开发者文档 → 认证接入。
媒体类型:
创建会话绑定当前IAM用户;资源读取与变更按用户归属校验。写入发生超时或响应丢失时,不应假定服务端未接纳并盲目重复请求。
- 模块:会话服务(session)
- 接口:GET
/api/openapi/app/v1/sessions/{session_id}/turns
请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| session_id | path | string | 是 | 创建会话接口返回的会话 ID。 |
| cursor | query | integer | 否 | 分页游标,不解析其内部含义;首次请求省略。 |
| limit | query | integer | 否 | 每页返回数量。 |
响应
| HTTP | 说明 |
|---|---|
| 200 | 请求成功 |
| default | 错误响应。按 code 判断具体错误,不能仅依赖 HTTP 状态码,多种错误可能共用状态码。 |
application/json。
响应200 TurnListResponse
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| has_more | boolean | 是 | — | 是否还有下一页;不要仅根据本页是否满额推断。 |
| items | array<TurnSummary> | 是 | — | 回合列表,最新在前;无回合时返回空数组,不为 null。 |
| next_cursor | integer | 是 | format="int64" | 下一页请求的 cursor;没有下一页时为 0。 |
响应200 TurnSummary
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| ended_at | string / null | 是 | ISO 8601 时间字符串 | 回合结束时间,ISO 8601;仍在运行时为 null。 |
| error | SessionError / null | 是 | — | 结构化失败信息;状态不是 failed 时为 null。 |
| final_message | string / null | 是 | — | 本轮最后一段连续文本,列表中可能截断,不等于完整回答。以工具调用结束且无展示文本时为 null;完整回答可由 agent_message_chunk 事件组合。 |
| final_message_truncated | boolean | 是 | — | 本次 final_message 是否被截断;完整文本通过回合详情接口读取。 |
| interrupt_reason | string / null | 是 | — | 回合中断原因;非 interrupted 状态时为 null。当前值为 user_requested、runtime_restarted、runtime_unavailable、session_ended、action_required_timeout;开放枚举,未知值不自动重试。 |
| output_count | integer / null | 是 | format="int64" | 本轮产物数量。0 表示无产物;null 表示未知而非零,此时查询回合详情。 |
| pending_action | PendingAction / null | 是 | — | 阻塞本轮的问题;仅 action_required 状态下非 null。列表直接返回完整问题,结构与会话详情一致,无需逐条查询才能识别待处理问题。 |
| started_at | string | 是 | ISO 8601 时间字符串 | 回合开始时间,ISO 8601,含微秒和时区。 |
| status | string | 是 | — | 回合执行状态,反映是否结束及结束结果;以此判断成功或异常,不以 stop_reason 代替。 |
| stop_reason | string / null | 是 | — | Agent 停止原因,例如 end_turn、max_tokens。运行中或未上报原因时为 null;异常结束也可能为 end_turn,成功与否应看 status。 |
| 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 | 是 | 选项标识兼展示文字;回答时原样提交。 |