千问办公企业旗舰版开发者文档:查询回合详情。
认证方式见APP开发者文档 → 认证接入。
媒体类型:
按
创建会话绑定当前IAM用户;资源读取与变更按用户归属校验。写入发生超时或响应丢失时,不应假定服务端未接纳并盲目重复请求。
- 模块:会话服务(session)
- 接口:GET
/api/openapi/app/v1/sessions/{session_id}/turns/{turn_id}
请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| session_id | path | string | 是 | 会话 ID。 |
| turn_id | path | string | 是 | 回合 ID,可从会话的回合列表中取得。 |
响应
| HTTP | 说明 |
|---|---|
| 200 | 请求成功 |
| default | 错误响应。按 code 判断具体错误,不能仅依赖 HTTP 状态码,多种错误可能共用状态码。 |
application/json。
响应200 TurnDetail
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| ended_at | string / null | 是 | ISO 8601 时间字符串 | 回合结束时间,ISO 8601;仍在运行时为 null。 |
| error | SessionError / null | 是 | — | 结构化失败信息;状态不是 failed 时为 null。 |
| final_message | string / null | 是 | — | 本轮最后一段连续文本,完整且未截断,但不等于全部回答。以工具调用结束且无展示文本时为 null。 |
| interrupt_reason | string / null | 是 | — | 回合中断原因;非 interrupted 状态时为 null。当前值为 user_requested、runtime_restarted、runtime_unavailable、session_ended、action_required_timeout;开放枚举,未知值不自动重试。 |
| items | array<TurnItem> | 是 | — | 本轮向用户展示的产物,无产物时为空数组。输出目录中的文件另由会话产物接口返回。列表的 output_count 非零而此数组为空时,可能读取不完整,可重试查询。 |
| pending_action | PendingAction / null | 是 | — | 阻塞本轮的问题;仅 action_required 状态下非 null。 |
| session_id | string | 是 | — | 此回合所属的会话 ID。 |
| started_at | string | 是 | ISO 8601 时间字符串 | 回合开始时间,ISO 8601,含微秒和时区。 |
| status | string | 是 | — | 回合执行状态;以此判断成功或异常结束,不以 stop_reason 代替。 |
| stop_reason | string / null | 是 | — | Agent 停止原因,例如 end_turn。运行中或未上报时为 null;异常结束也可能为 end_turn,成功与否应看 status。 |
| turn_id | string | 是 | — | 当前回合 ID。 |
TurnItem 类型分派
按 type 选择下方结构:file 对应 TurnItemFileItem,web_app 对应 TurnItemWebAppItem,document_review 对应 TurnItemDocumentReviewItem。未知类型保留公共字段并跳过不认识的载荷,不让整个回合读取失败。
响应200 TurnItemFileItem
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| created_at | string | 是 | ISO 8601 时间字符串 | 产物生成时间,ISO 8601,含微秒和时区。 |
| file | TurnItemFile | 是 | — | 该项展示的文件元数据,字段见 TurnItemFile。 |
| tool_call_id | string | 否 | — | 生成该产物的工具调用 ID,可关联事件流中的 tool_call / tool_call_update。 |
| type | string | 是 | enum=["file"] | 产物类型,决定其他字段的结构;开放枚举,未知类型应跳过而非导致整个响应处理失败。 |
响应200 TurnItemFile
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| alt | string | 否 | — | Agent 对文件的描述,可作为标题或替代文本。 |
| barn_id | string | 否 | — | 存储标识,用于换取下载 URL。 |
| mime_type | string | 否 | — | MIME 类型,例如 application/pdf。 |
| path | string | 是 | — | 文件存储路径,不是 URL。读取文件时再换取下载链接;预签名链接会过期,因此不在这里固定返回。 |
| size | integer | 否 | format="int64" | 大小,单位字节。 |
响应200 TurnItemWebAppItem
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| created_at | string | 是 | ISO 8601 时间字符串 | 产物生成时间,ISO 8601,含微秒和时区。 |
| tool_call_id | string | 否 | — | 生成该产物的工具调用 ID,可关联事件流中的 tool_call / tool_call_update。 |
| type | string | 是 | enum=["web_app"] | 产物类型,决定其他字段的结构;开放枚举,未知类型应跳过而非导致整个响应处理失败。 |
| web_app | TurnItemWebApp | 是 | — | 该项展示的应用产物,字段见 TurnItemWebApp。 |
响应200 TurnItemWebApp
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| live_preview | boolean | 否 | — | 本轮是否提供过可能仍可访问的应用预览。此处仅返回标记,短期地址需通过会话产物接口的 live 查询。 |
| published_url | string | 否 | — | 已发布页面的持久地址,仅实际发布后返回,可保存和分享;有效期不依赖当前运行实例。 |
| source_dir | string | 否 | — | 应用在会话工作区中的目录。 |
| static | boolean | 否 | — | 是否为静态站点。静态站点可持久发布;动态应用依赖运行中的服务。 |
响应200 TurnItemDocumentReviewItem
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| created_at | string | 是 | ISO 8601 时间字符串 | 产物生成时间,ISO 8601,含微秒和时区。 |
| document_review | TurnItemDocumentReview | 是 | — | 该项展示的文档审阅结果,字段见 TurnItemDocumentReview。 |
| tool_call_id | string | 否 | — | 生成该产物的工具调用 ID,可关联事件流中的 tool_call / tool_call_update。 |
| type | string | 是 | enum=["document_review"] | 产物类型,决定其他字段的结构;开放枚举,未知类型应跳过而非导致整个响应处理失败。 |
响应200 TurnItemDocumentReview
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| findings | array<string> | 否 | — | 发现的问题,仅 verdict=failed 时返回。 |
| path | string | 否 | — | 被审阅文档的工作区路径,用于区分同一回合中多个文档的审阅结果。 |
| verdict | string | 是 | — | passed 表示通过,failed 表示未通过。 |
响应200 TurnItemUnknownItem
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| created_at | string | 是 | ISO 8601 时间字符串 | 产物生成时间,ISO 8601,含微秒和时区。 |
| tool_call_id | string | 否 | — | 生成该产物的工具调用 ID,可关联事件流中的 tool_call / tool_call_update。 |
| type | string | 是 | — | 产物类型,决定其他字段的结构;开放枚举,未知类型应跳过而非导致整个响应处理失败。 |
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 | 是 | 选项标识兼展示文字;回答时原样提交。 |