Skip to main content

查询执行回合

千问办公企业旗舰版开发者文档:查询执行回合。

认证方式见APP开发者文档 → 认证接入。
  • 模块:会话服务(session)
  • 接口:GET/api/openapi/app/v1/sessions/{session_id}/turns

请求参数

参数位置类型必填说明
session_idpathstring是创建会话接口返回的会话 ID。
cursorqueryinteger否分页游标,不解析其内部含义;首次请求省略。
limitqueryinteger否每页返回数量。

响应

HTTP说明
200请求成功
default错误响应。按 code 判断具体错误,不能仅依赖 HTTP 状态码,多种错误可能共用状态码。
媒体类型:application/json。

响应200 TurnListResponse

字段类型必填约束契约说明
has_moreboolean是—是否还有下一页;不要仅根据本页是否满额推断。
itemsarray<TurnSummary>是—回合列表,最新在前;无回合时返回空数组,不为 null。
next_cursorinteger是format="int64"下一页请求的 cursor;没有下一页时为 0。

响应200 TurnSummary

字段类型必填约束契约说明
ended_atstring / null是ISO 8601 时间字符串回合结束时间,ISO 8601;仍在运行时为 null。
errorSessionError / null是—结构化失败信息;状态不是 failed 时为 null。
final_messagestring / null是—本轮最后一段连续文本,列表中可能截断,不等于完整回答。以工具调用结束且无展示文本时为 null;完整回答可由 agent_message_chunk 事件组合。
final_message_truncatedboolean是—本次 final_message 是否被截断;完整文本通过回合详情接口读取。
interrupt_reasonstring / null是—回合中断原因;非 interrupted 状态时为 null。当前值为 user_requested、runtime_restarted、runtime_unavailable、session_ended、action_required_timeout;开放枚举,未知值不自动重试。
output_countinteger / null是format="int64"本轮产物数量。0 表示无产物;null 表示未知而非零,此时查询回合详情。
pending_actionPendingAction / null是—阻塞本轮的问题;仅 action_required 状态下非 null。列表直接返回完整问题,结构与会话详情一致,无需逐条查询才能识别待处理问题。
started_atstring是ISO 8601 时间字符串回合开始时间,ISO 8601,含微秒和时区。
statusstring是—回合执行状态,反映是否结束及结束结果;以此判断成功或异常,不以 stop_reason 代替。
stop_reasonstring / null是—Agent 停止原因,例如 end_turn、max_tokens。运行中或未上报原因时为 null;异常结束也可能为 end_turn,成功与否应看 status。
turn_idstring是—回合 ID,可用于查询完整回合详情,包括未截断文本和产物。

SessionError

字段类型必填说明
categorystring否错误分类:quota、auth、permission、rate_limit、model_unavailable、timeout、content_rejected、input_too_large、input_invalid、limit_reached、service_error、unknown;开放枚举。
codestring是机器可识别的错误码;未知值按一般失败处理。
messagestring是供展示和排查的错误文字,不作为程序分支条件。
remedystring否建议处理方式:retry、retry_after_backoff、switch_model、new_session、modify_input、reauthenticate、top_up_quota、contact_admin、refresh、report。按此字段决定下一步;未知值不盲目重试。
trace_idstring否服务端请求追踪标识,用于故障排查。

PendingAction

字段类型必填说明
asked_atstring是Agent 提问时间,ISO 8601,含微秒和时区。
questionsarray<Question>是待展示的问题数组;answers 按相同顺序提交。
tool_call_idstring是提交问题回答时原样传回的工具调用标识。

Question

字段类型必填说明
headerstring否可选的问题短标题。
multi_selectboolean是是否允许多选。每道题仍对应一个 answers 字符串;多选作为文本交给 Agent 解释,单选传选项 label。
optionsarray<QuestionOption>否可选项;省略或为空时允许自由文本回答。
questionstring是问题正文。

QuestionOption

字段类型必填说明
descriptionstring否选择此选项的补充说明。
labelstring是选项标识兼展示文字;回答时原样提交。

使用说明

创建会话绑定当前IAM用户;资源读取与变更按用户归属校验。写入发生超时或响应丢失时,不应假定服务端未接纳并盲目重复请求。