一、功能概述
任务运行期间，业务后端有两种途径获取 AI 机器人的状态与对话数据：
| 获取方式 | 途径 | 可获取内容 | 实时性 |
| 查询接口（主动拉取） | 任务生命周期五类标准操作中的查询任务接口。 | 任务运行状态、对话上下文历史。 | 按需查询，返回查询时刻的快照。 |
| 服务端回调（被动推送） | AI 状态流转回调。 | 机器人的对话状态实时流转。 | 实时推送，无轮询延迟。 |
注意：说明：
注意：客户端 SDK 也有对应的状态获取通道（状态事件），与服务端回调共用同一套状态码定义，端侧接入详细参见 （客户端）接收 AI 机器人状态。
二、通过查询接口获取
查询任务接口通过 DescribeType 区分两类查询：
| DescribeType | 查询内容 | 返回字段 |
| 0（默认） | 任务运行状态 | Status / StartTime |
| 1 | 对话上下文历史 | HistoryContents（用户与 AI 的历史对话列表） |
三、查询任务运行状态（DescribeType = 0）
输入参数：
| 参数名 | 必选 | 类型 | 描述 |
| SdkAppId | 是 | Integer | TRTC 应用 ID。 |
| TaskId | 是 | String | 任务 ID。 |
| DescribeType | 否 | Integer | 0：查询任务状态（默认）。 |
输出参数：
| 参数名 | 类型 | 描述 |
| Status | String | 任务状态，见下方状态表。 |
| StartTime | Integer | 任务启动时间（UTC 毫秒）。 |
| RequestId | String | 请求 ID。 |
任务状态（Status）取值：
| Status | 含义 |
| InProgress | 任务运行中。 |
| Idle | 空闲（任务创建后、正式启动前）。 |
| Exited | 已退出（任务已结束）。 |
请求示例：
{ "SdkAppId": 1400704311, "TaskId": "-m9jX35U7sY4p8GEKc0d4EnvzOlwCUTb…", "DescribeType": 0}
响应示例：
{ "Response": { "Status": "InProgress", "StartTime": 1751196050000, "TaskId": "-m9jX35U7sY4p8GEKc0d4EnvzOlwCUTb…", "RequestId": "req-xxx" }}
四、查询对话上下文历史（DescribeType = 1）
返回当前任务内用户与 AI 的历史对话内容，可用于客服质检、审计落库、用户重连后恢复上下文等场景。
输出参数：
| 参数名 | 类型 | 描述 |
| HistoryContents | Array of Object | 对话历史列表，每项含 Role（user=用户 / assistant=AI）与 Content（对话文本）。 |
| Status | String | 任务状态。 |
| StartTime | Integer | 任务启动时间（UTC 毫秒）。 |
请求示例：
{ "SdkAppId": 1400704311, "TaskId": "-m9jX35U7sY4p8GEKc0d4EnvzOlwCUTb…", "DescribeType": 1}
响应示例：
{ "Response": { "StartTime": 1790542649581, "Status": "InProgress", "TaskId": "-nE5D7FU7k85T+dH1Mf-xdCO5s+…", "HistoryContents": [ {"Role": "user", "Content": "今天天气怎么样？帮我查一下北京的温度。"}, {"Role": "assistant", "Content": "我无法获取实时天气，建议用天气App查北京温度。"}, {"Role": "user", "Content": "请把下面这句话原样读出来：高优插播"}, {"Role": "assistant", "Content": "高优插播"}, {"Role": "user", "Content": "今天天气怎么样？帮我查一下北京的温度。"}, {"Role": "assistant", "Content": "无法获取实时天气，请用天气App查询北京温度。"} ], "RequestId": "req-xxx" }}
注意：S2S（端到端）模式不支持查询对话历史，DescribeType=1 时返回为空。
五、AI 状态流转回调
任务运行期间，机器人每发生一次对话状态流转，TRTC 后台即向业务回调 URL 实时推送一条 AI 状态流转事件，无需业务侧轮询。
回调 Payload 关键字段：
| 字段名 | 类型 | 描述 |
| State.Code | Integer | 机器人对话状态码，见下表。 |
| State.Desc | String | 状态描述。 |
| Timestamp | Integer | 状态流转时间戳（毫秒）。 |
回调示例（EventInfo.Payload 部分）：
{ "Payload": { "State": { "Code": 2, "Desc": "AI 思考中（LLM 推理）" }, "Timestamp": 1751196060800 }}
注意：说明：
注意：回调报文的完整结构（事件组、事件类型枚举、回调 URL 配置与 X-TRTC-Signature 签名校验）详细参见 AI 对话回调事件。
六、机器人对话状态码（State.Code）
State.Code 描述的是一轮对话中机器人的实时状态，客户端 SDK 的状态事件与服务端状态流转回调共用同一套定义：
| State.Code | 含义 | 对应链路阶段 |
| 0 | AI 空闲中 | 等待用户开口。 |
| 1 | AI 聆听中 | ASR 识别中（用户说话中），一轮对话的开始信号。 |
| 2 | AI 思考中 | LLM 推理中。 |
| 3 | AI 说话中 | TTS 播报中。 |
| 4 | AI 被打断 | 轮次提前终止。 |
| 5 | AI 已说完 | 轮次正常结束。 |
一轮对话的典型状态流转：
·正常路径：用户开口（1）→ LLM 推理（2）→ TTS 播报（3）→ 播报完成（5）→ 回到空闲（0）等待下一轮。
·打断路径：播报中（3）被用户打断或收到打断指令，直接流转为被打断（4）→ 回到空闲（0）。打断的触发方式详细参见 （客户端）打断指令。
七、两类状态的区分
查询接口返回的 Status（任务状态）与回调推送的 State.Code（对话状态）是两个不同层级的状态，注意区分：
| 对比项 | 任务状态（Status） | 对话状态（State.Code） |
| 描述层级 | 任务生命周期。 | 单轮对话生命周期。 |
| 获取方式 | 查询接口（DescribeType=0）/ 任务结束回调。 | AI 状态流转回调 / 客户端状态事件。 |
| 类型与取值 | String：InProgress 运行中；Idle 空闲；Exited 已退出。 | Integer：0 空闲；1 聆听中；2 思考中；3 说话中；4 被打断；5 已说完。 |
| 典型用途 | 任务级监控、存活巡检、故障告警。 | 对话过程展示、打断检测、轮次统计。 |
注意：说明：
注意：任务级的状态变化（启动完成、结束及退出原因等）通过任务启动 / 结束回调推送，详细参见 AI 对话回调事件。
八、典型应用场景
| 场景 | 实现方式 | 说明 |
| 对话质检与审计 | 查询接口 DescribeType=1 | 会话结束后拉取完整对话上下文，落库用于质检、审计与合规。 |
| 任务监控告警 | 查询接口 DescribeType=0 轮询 / 任务结束回调 | 发现任务 Exited（已退出）及时告警，结合退出码判断是否为异常退出。 |
| 实时状态大屏 | 订阅 AI 状态流转回调 | 回调实时驱动机器人状态展示（聆听中 / 思考中 / 说话中），无需轮询。 |
| 轮次统计分析 | 累计状态流转回调 | 基于 1→5 完整流转统计轮次数，基于 4 统计打断率。 |
| 重连恢复上下文 | 查询接口 DescribeType=1 | 用户断线重连或切换设备后，拉取历史对话恢复上下文继续服务。 |
九、注意事项
1. S2S 模式不支持查询对话历史：端到端模式下 DescribeType=1 返回为空；如需对话记录请通过字幕回调 / 状态回调自行落库。
2. 查询返回的是快照：查询接口返回查询时刻的状态，如需实时感知状态变化请订阅状态流转回调，不要依赖轮询（轮询既有时延又消耗接口 QPS 配额）。
3. 回调必须校验签名：业务后端收到回调后须校验 X-TRTC-Signature 签名防止伪造，配置方式见 AI 对话回调事件。
4. 任务退出排查：查询到 Status 为 Exited 时，建议结合任务结束回调的退出码与 ASR / LLM 回调定位退出原因（区分正常结束与异常失败）。
5. 状态回调可能重复：网络重传等情况下回调可能重复投递，业务侧需按 TaskId + Timestamp 做幂等处理。