帮你快速理解、总结文档立即下载
文档中心>实时音视频>AI 实时对话>AI 实时对话 2.0>基础功能>获取 AI 机器人状态以及上下文

获取 AI 机器人状态以及上下文

最近更新时间：2026-11-06 17:00:41
我的收藏

本页目录：

功能概述

任务运行期间，业务后端有两种途径获取 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 做幂等处理。
中国站