Skip to main content

查询回合详情

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

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

请求参数

参数位置类型必填说明
session_idpathstring是会话 ID。
turn_idpathstring是回合 ID,可从会话的回合列表中取得。

响应

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

响应200 TurnDetail

字段类型必填约束契约说明
ended_atstring / null是ISO 8601 时间字符串回合结束时间,ISO 8601;仍在运行时为 null。
errorSessionError / null是—结构化失败信息;状态不是 failed 时为 null。
final_messagestring / null是—本轮最后一段连续文本,完整且未截断,但不等于全部回答。以工具调用结束且无展示文本时为 null。
interrupt_reasonstring / null是—回合中断原因;非 interrupted 状态时为 null。当前值为 user_requested、runtime_restarted、runtime_unavailable、session_ended、action_required_timeout;开放枚举,未知值不自动重试。
itemsarray<TurnItem>是—本轮向用户展示的产物,无产物时为空数组。输出目录中的文件另由会话产物接口返回。列表的 output_count 非零而此数组为空时,可能读取不完整,可重试查询。
pending_actionPendingAction / null是—阻塞本轮的问题;仅 action_required 状态下非 null。
session_idstring是—此回合所属的会话 ID。
started_atstring是ISO 8601 时间字符串回合开始时间,ISO 8601,含微秒和时区。
statusstring是—回合执行状态;以此判断成功或异常结束,不以 stop_reason 代替。
stop_reasonstring / null是—Agent 停止原因,例如 end_turn。运行中或未上报时为 null;异常结束也可能为 end_turn,成功与否应看 status。
turn_idstring是—当前回合 ID。

TurnItem 类型分派

按 type 选择下方结构:file 对应 TurnItemFileItem,web_app 对应 TurnItemWebAppItem,document_review 对应 TurnItemDocumentReviewItem。未知类型保留公共字段并跳过不认识的载荷,不让整个回合读取失败。

响应200 TurnItemFileItem

字段类型必填约束契约说明
created_atstring是ISO 8601 时间字符串产物生成时间,ISO 8601,含微秒和时区。
fileTurnItemFile是—该项展示的文件元数据,字段见 TurnItemFile。
tool_call_idstring否—生成该产物的工具调用 ID,可关联事件流中的 tool_call / tool_call_update。
typestring是enum=["file"]产物类型,决定其他字段的结构;开放枚举,未知类型应跳过而非导致整个响应处理失败。

响应200 TurnItemFile

字段类型必填约束契约说明
altstring否—Agent 对文件的描述,可作为标题或替代文本。
barn_idstring否—存储标识,用于换取下载 URL。
mime_typestring否—MIME 类型,例如 application/pdf。
pathstring是—文件存储路径,不是 URL。读取文件时再换取下载链接;预签名链接会过期,因此不在这里固定返回。
sizeinteger否format="int64"大小,单位字节。

响应200 TurnItemWebAppItem

字段类型必填约束契约说明
created_atstring是ISO 8601 时间字符串产物生成时间,ISO 8601,含微秒和时区。
tool_call_idstring否—生成该产物的工具调用 ID,可关联事件流中的 tool_call / tool_call_update。
typestring是enum=["web_app"]产物类型,决定其他字段的结构;开放枚举,未知类型应跳过而非导致整个响应处理失败。
web_appTurnItemWebApp是—该项展示的应用产物,字段见 TurnItemWebApp。

响应200 TurnItemWebApp

字段类型必填约束契约说明
live_previewboolean否—本轮是否提供过可能仍可访问的应用预览。此处仅返回标记,短期地址需通过会话产物接口的 live 查询。
published_urlstring否—已发布页面的持久地址,仅实际发布后返回,可保存和分享;有效期不依赖当前运行实例。
source_dirstring否—应用在会话工作区中的目录。
staticboolean否—是否为静态站点。静态站点可持久发布;动态应用依赖运行中的服务。

响应200 TurnItemDocumentReviewItem

字段类型必填约束契约说明
created_atstring是ISO 8601 时间字符串产物生成时间,ISO 8601,含微秒和时区。
document_reviewTurnItemDocumentReview是—该项展示的文档审阅结果,字段见 TurnItemDocumentReview。
tool_call_idstring否—生成该产物的工具调用 ID,可关联事件流中的 tool_call / tool_call_update。
typestring是enum=["document_review"]产物类型,决定其他字段的结构;开放枚举,未知类型应跳过而非导致整个响应处理失败。

响应200 TurnItemDocumentReview

字段类型必填约束契约说明
findingsarray<string>否—发现的问题,仅 verdict=failed 时返回。
pathstring否—被审阅文档的工作区路径,用于区分同一回合中多个文档的审阅结果。
verdictstring是—passed 表示通过,failed 表示未通过。

响应200 TurnItemUnknownItem

字段类型必填约束契约说明
created_atstring是ISO 8601 时间字符串产物生成时间,ISO 8601,含微秒和时区。
tool_call_idstring否—生成该产物的工具调用 ID,可关联事件流中的 tool_call / tool_call_update。
typestring是—产物类型,决定其他字段的结构;开放枚举,未知类型应跳过而非导致整个响应处理失败。

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用户;资源读取与变更按用户归属校验。写入发生超时或响应丢失时,不应假定服务端未接纳并盲目重复请求。