跳转到内容

Realtime 语音

通过 Realtime 语音,让 End User 在已有 Session 中与 Agent 交谈。本指南说明浏览器和设备如何接入已实现的 tidb-link.realtime.v1 契约。API 参考和可下载的 OpenAPI定义 REST 请求与响应字段。

Realtime 与文字交互使用同一个普通 Session。打开 Realtime Connection 保留该 Session 的所有者与当前 Configuration Epoch。一个 Session 最多有一个活跃的 Realtime Connection,同一个 User 可以在多个 Session 中交谈。WebSocket 是连接的传输通道,断开 WebSocket 与结束 Realtime Connection 是不同操作。

打开语音前读取 Session 响应的 realtimeVoice。null 表示仅文字,语音连接返回 409 realtime_not_enabled;对象中的 language 将本 Session 的语音回复、任务播报和重连固定为 zh-CN 或 en-US。这不保证当前服务可用;供应商不支持时返回 realtime_language_unsupported。缺少设置的历史 Session 按中文开启。该设置不限制普通文字交互,客户端不能通过 session.update 覆盖语言。

能力 应用可以做什么
同一 Session 中的语音与文字 将语音附加到已有会话,通过 Session Timeline 读取已保存的文字与 Realtime 事实。
流式语音 发送麦克风音频、播放回复,并显示部分或最终转写。
自由对话或按住说话 由服务提供方检测语音边界,或由客户端标记一句话的开始与结束。
Full Agent 任务 用语音提出工作要求,接收关联持久 Turn 的任务接纳、进度和结果。
常驻任务(Standing Task) 让模板定义的 Full Agent 任务持续运行,使设备或传感器事件可以让 Agent 先开口。
播放打断 用户打断时立即停止缓冲音频,报告最后实际播放的音频块。
连接恢复 为同一活跃连接获取新 token,通过 Session 查询恢复持久任务状态。

Realtime Model 负责语音交谈。它委派任务时,Full Agent 使用 Session 固定的配置和启用工具执行 Turn。进度和结果再回到语音会话。普通 Realtime 闲聊不会创建 Full Agent Turn。口头确认或进度消息与任务的持久结果是不同事实。

对于已启用语音的 Session,Realtime Model 与 Full Agent 收到同一份配置的 Agent Template Instructions,共享业务身份、目标、对话流程和信息来源约束。已有模板无需修改 Instructions 或重新发布。涉及工具、Skill 或执行的要求仍委派给 Full Agent,语音回复遵循 Session 固定的 Realtime 语言。

同一个 Session 可以同时包含文字与 Realtime 交互。共享历史不保证完整恢复服务提供方的上下文,也不保证进程丢失后恢复任务订阅;下文的恢复限制仍然适用。

使用 End User 的 API Key 调用 GET /api/v1/realtime-models。响应包含 defaultModel 和 models;每项提供 id、label、available、isDefault、languages、endpointingModes 以及输入、输出方向的 audio 格式列表。音频列表包含平台转换后客户端可用的格式。暂不可用的模型仍保留在列表中,默认模型不可用时不会自动换成其他模型。

在创建 Session时传入 { "agentTemplateId": "<template-id>", "realtimeModel": "<published-id>" }。省略时,已启用语音的 Session 保存当时的发布默认模型;关闭语音的 Session 保存 null。关闭语音时,在创建或修改接口中显式选择模型均返回 409 realtime_not_enabled。没有默认模型时也保存 null,文字交互仍可使用。Session 响应返回 realtimeModel、realtimeModelRevision 和 realtimeModelEtag。

修改选择:

终端窗口
curl -X PATCH 'https://<your-agent-service-host>/api/v1/user/sessions/<session-id>/realtime-model' \
-H 'Authorization: Bearer <user-api-key>' \
-H 'Content-Type: application/json' \
-H 'If-Match: <Session JSON 中的 realtimeModelEtag,保留引号>' \
-d '{"realtimeModel":"<published-id>"}'

缺少 If-Match 返回 428;旧 token 返回 412 realtime_model_conflict,此时先重新读取 Session。语音模型修订与文本模型独立,选择不变时不推进修订。创建或修改时指定未发布的 id 返回 409 realtime_model_unavailable。

建立 Realtime Connection 时固定所选模型 id 和服务提供方身份。Session 改选只影响下一条连接;当前连接的 WebSocket 重连、服务提供方轮换及运行时替换仍保留原模型。所选模型撤下后,新连接返回 409 realtime_model_unavailable,需要显式选择其他模型。语言和音频格式也按所选模型的能力校验。

升级前创建的 Session 保留 null,在连接建立时使用当时的默认模型;升级后创建的已启用语音 Session 保存创建时的默认值,之后更换发布默认模型不会改变它。重复创建请求仍使用原来的去重身份:仅显式传入的 realtimeModel 计入标识,省略字段的旧请求可跨升级重试。

使用 Organization Key 打开的连接保留授权时的精确凭证。轮换或撤销该凭证会结束它授权的连接,并使未兑换的 connect token 失效;其他 Key 的连接不受影响。已经接受的普通 Turn 和常驻 Turn 按既有执行规则继续,但已结束的连接不再播报,也不启动下一轮常驻任务。用有效 Key 从 Session 历史恢复结果,再在同一 Session 上打开新连接。新凭证不能恢复旧连接或旧 token。各副本会收敛关闭 socket,不承诺瞬时物理断开。

1. 在你的后端打开 Realtime Connection

Section titled “1. 在你的后端打开 Realtime Connection”

从 End User 拥有的已有 Session 开始,参照快速开始。服务运营方需要发布可用的 Realtime 模型。连接接纳成功本身不能证明语音服务提供方可用。

客户后端可使用自己的 Organization API Key,通过 POST /api/v1/org/users/<userId>/sessions/<sessionId>/realtime 显式选择普通 End User。同一路径的 GET、DELETE 和 POST …/connect-tokens 使用相同范围。返回的 WebSocket URL 和 token 握手保持不变。已停用 owner 可以查看和结束现有连接,但不能新建连接或获取 token。也可以继续使用该 User 的 API Key。浏览器和设备从你的后端获取短期连接授权,不在固件中保存 User Key。先将获取授权的应用请求认证为该 End User,并确认 Session 属于他,再向服务转发请求。

终端窗口
curl -X POST 'https://<your-agent-service-host>/api/v1/user/sessions/<session-id>/realtime' \
-H 'Authorization: Bearer <user-api-key>'

201 响应包含状态为 connecting 的 realtimeConnection,以及 websocketUrl、connectToken 和 connectTokenExpiresAt。把这三个授权字段交给客户端。token 签发后 60 秒过期,只能授权一次 session.connect,跨副本也不能重用。不要把它放入 URL、日志或持久客户端存储。每次连接尝试都需要新 token。

始终没有接入的连接会在 120 秒后自动过期。仅连接 token 过期不会结束连接;连接仍然活跃时,为它签发新 token,不要重复创建连接。

音频默认为单声道 PCM16:输入 16 kHz,输出 24 kHz。可以发送可选 JSON 请求体选择格式,例如:

{
"audio": {
"input": { "encoding": "pcm16", "sampleRate": 16000, "channels": 1 },
"output": {
"encoding": "opus",
"sampleRate": 24000,
"channels": 1,
"packetDurationMs": 20,
"bitrate": 24000
}
}
}

发送请求体时包含 Content-Type: application/json。省略的方向使用 PCM16 默认值。支持的单声道格式如下:

方向 编码 sampleRate(Hz) packetDurationMs bitrate(bps)
输入 pcm16 8000 或 16000(默认) 省略 省略
输出 pcm16 8000、16000 或 24000(默认) 省略 省略
输入 opus 16000 20(默认)、40 或 60 省略
输出 opus 24000 20 16000、24000 或 32000(默认)

需要较低采样率时,在创建连接的 audio.input.sampleRate 或 audio.output.sampleRate 中选择。服务器通过连续低通滤波,将 8 kHz 输入升采样为模型所需的 16 kHz,将模型的 24 kHz 输出降采样为选定的较低采样率。客户端按 session.ready 回显的实际采样率采集和播放。8 kHz 是电话音质,可能降低语音识别准确率;适合愿意用音质换取较小缓冲的设备。

PCM16 输出块长度可能不同,包括回复结束时较短的滤波尾部;按协商采样率播放全部负载采样,并用服务器提供的块索引报告播放进度。服务器在接纳连接之前用 400 audio_format_unsupported 拒绝不支持的格式或服务提供方组合。

可以按音频负载占用的内存选择格式。所有格式均为单声道;下表不含 5 字节二进制帧头、WebSocket/网络开销、包管理信息和编解码器工作内存。较低采样率能减少每秒占用的内存和带宽;长回复到达速度超过播放速度时,仍可能溢出。

方向 编码 采样率 码率 音频块或包负载 每秒音频字节数
上行 PCM16 8000 Hz 128 kbps 客户端分块;每 20 ms 为 320 字节 16000
上行 PCM16(默认) 16000 Hz 256 kbps 客户端分块;每 20 ms 为 640 字节 32000
下行 PCM16 8000 Hz 128 kbps 可变长度分块;每 20 ms 为 320 字节 16000
下行 PCM16 16000 Hz 256 kbps 可变长度分块;每 20 ms 为 640 字节 32000
下行 PCM16(默认) 24000 Hz 384 kbps 服务提供方分块;每 20 ms 为 960 字节 48000
上行 Opus 16000 Hz 设备编码器自行选择,建议 16–32 kbps 20(默认)、40 或 60 ms 取决于设备编码器
下行 Opus 24000 Hz bitrate: 16000(16 kbps) 20 ms;40 字节 2000
下行 Opus 24000 Hz bitrate: 24000(24 kbps) 20 ms;60 字节 3000
下行 Opus 24000 Hz bitrate: 32000(32 kbps,Opus 默认值) 20 ms;80 字节 4000

audio.output.bitrate 的单位为比特/秒,只接受 16000、24000 或 32000。新建 Opus 下行连接使用固定码率(CBR),省略时默认 32000;这取代了此前编解码库默认 64000 bps 的可变码率(VBR)行为。码率协商功能上线前已接纳的连接可以不带此字段,并保留原有编解码行为。PCM16 或任何上行格式带 bitrate 都会被拒绝,错误码为 audio_format_unsupported;Opus 上行的码率由设备编码器控制。

实际生效的下行码率会在 realtimeConnection.audio.output、session.ready.audio.output 和 Session 的实时状态 realtime.audio.output 中回显。要获得内存收益,设备需要缓存压缩后的 Opus 包,在播放时解码;降低码率本身不能防止长回复突发下发时缓冲区溢出。

格式在 Realtime Connection 的整个生命周期中固定。要改格式,先结束连接,再在同一个 Session 上打开新连接。session.update 当前只改变语音端点检测模式。虽然其 schema 接受 audio 和 voice,这些字段不会改变运行中的连接。

打开连接返回 409 realtime_connection_live 时,读取 GET /api/v1/user/sessions/<session-id>/realtime。用新授权恢复已有连接,或先显式结束它再打开新连接。GET 返回最新连接的 { "realtimeConnection": ... },包括已结束的连接,但不签发 token。

使用 WebSocket 子协议 tidb-link.realtime.v1 打开返回的 websocketUrl。WebSocket 打开后及时将下面的 JSON 文本帧作为第一条消息发送,默认握手期限为 10 秒:

{
"type": "session.connect",
"connect_token": "<connectToken>",
"endpointing": { "mode": "client" }
}

授权中的 connectToken 在第一帧里写为 connect_token。保留各事件 schema 的字段名;共享连接与音频对象仍使用 sessionId、sampleRate 等字段。认证在第一帧完成,WebSocket 不携带 User Key。token 必须属于 URL 中指定的 Session。缺失、过期、已使用或不匹配的 token 会被拒绝。服务器繁忙时,可能以 HTTP 429 拒绝 WebSocket 升级(浏览器只会将其报告为连接失败)。这种拒绝不会消耗 token:在 token 过期前以有界退避重试,或签发新 token。服务器未能在握手期限内完成你的 session.connect 时,会以 provider_unavailable 关闭。发送 session.connect 之后收到的任何 provider_unavailable 都可能已消耗 token;若重试返回 invalid_connect_token,请签发新 token。

收到 session.ready 后再发送音频或其他客户端事件。与握手并发的帧可能被丢弃。就绪事件包含 realtime_connection、实际生效的 audio.input、audio.output 和 endpointing.mode,据此配置采集与播放。REST 响应中的 connecting 表示已接纳;session.ready 才表示服务提供方已打开。首帧请求了可选 capabilities 时,session.ready 还会列出被接受的能力,见设备控制下行节奏。

端点检测决定用户的一句话何时结束:

  • client:在一句话的音频之前发送 input_audio.activity,其 kind 为 start;最后一个音频帧之后发送 kind: end。按住说话按钮或本地 VAD 可以决定这些边界。达到你选定的静音窗口后及时发送结束事件。
  • server:持续传输麦克风音频,由服务提供方检测语音及其结束。在此模式下,客户端 activity 事件被忽略。

首次连接省略 endpointing 时,配置模型支持 client 就选择它,否则选择 server。重连时省略则保留当前模式。请求不支持的模式会返回 endpointing_unsupported;签发新 token 后用支持的模式重试,或省略模式选择。被拒绝的握手已经消耗旧 token。

在已打开的 WebSocket 上请求切换模式:

{ "type": "session.update", "event_id": "mode-change-1", "endpointing": { "mode": "server" } }

等 session.updated 确认后再应用新模式。运行中的服务提供方连接只能在其支持的模式之间切换。拒绝切换时,旧模式仍然可用;使用另一种模式可能需要结束并新建 Realtime Connection。仅重连 WebSocket 会保留活跃的服务提供方连接。

服务器每 15 秒发送 WebSocket 协议 ping 帧,并关闭 30 秒未回复的 WebSocket。浏览器 WebSocket 实现会自动回复;设备库需要支持 pong。没有 JSON 心跳事件。

默认输入需要采集或重采样为 16 kHz 单声道,并将有符号 PCM16 采样编码为小端字节序。20 ms 的一帧包含 320 个采样,即 640 个负载字节。浏览器麦克风通常输出另一采样率的浮点采样,直接转发原始字节不会得到有效 PCM16。客户端需要完成转换。浏览器播放时,在用户操作中解锁 AudioContext。

音频可以使用下面任一种载体。控制事件和转写事件始终使用 JSON 文本帧。

二进制帧包含五字节头部,其后是编码后的音频:

字节 输入:客户端到服务器 输出:服务器到客户端
0 0x01 0x02
1..4 无符号 32 位帧计数器,大端 无符号 32 位 chunk_index,大端
5.. 协商后的输入音频 协商后的输出音频

头部字节序与 PCM16 采样的小端字节序相互独立。负载最多 64 KiB,PCM16 负载长度为偶数。Opus 负载恰好包含一个协商时长的原始 Opus 包,不含 Ogg 或 WebM 容器。Opus 音频块索引按包计数。

下面的浏览器辅助函数在就绪后发送已经编码的输入负载:

function sendAudioFrame(socket, sequence, payload) {
const frame = new Uint8Array(5 + payload.byteLength);
const header = new DataView(frame.buffer);
header.setUint8(0, 0x01);
header.setUint32(1, sequence, false);
frame.set(payload, 5);
socket.send(frame);
}

设置 socket.binaryType = 'arraybuffer',让浏览器以 ArrayBuffer 接收二进制消息。读取输出类型 0x02,用 getUint32(1, false) 读取音频块索引,从字节 5 起读取音频。将这些音频块关联到最近的 response.started.response_id。二进制音频帧本身没有响应 ID,同一时刻只流式输出一个响应。

也可以发送 input_audio.append,其 base64 只编码音频负载,不包含二进制头部:

{ "type": "input_audio.append", "audio": "<base64 encoded audio payload>" }

服务器随后发送 response.audio.delta,包含 response_id、从零开始的 chunk_index 和 base64 audio。按协商的输出格式解码音频字段。

服务器初始以二进制发送音频,此后跟随客户端最近一个音频帧的载体。重连后重新从二进制开始。即使客户端偏好 JSON 输入,也要处理二进制输出和 response.audio.delta。

所有 Opus 下行响应的第一个包都由新的编码器状态产生,无论是否启用流控。客户端应在每个 response.started 处重置解码器。如果无法准备新的编码器状态,服务器会在发送该响应之前以不可恢复的 provider_unavailable 错误结束连接。

客户端端点检测模式下,每句话按顺序发送:JSON { "type": "input_audio.activity", "kind": "start" }、音频帧、JSON { "type": "input_audio.activity", "kind": "end" }。音频随采集流式传输,不是上传完整录音。服务器端点检测模式只需要音频帧。

用以下服务端事件驱动会话界面:

事件 客户端操作
transcript.partial 更新 role: user 或 assistant 的临时文字;存在 response_id 时用它关联助手文字。
transcript.final 显示最终确定的文字片段,一句话可以有多个最终片段。
response.started 用 response_id 标识新输出响应,保留其 kind 和可选 turn_id。
response.audio.delta 或二进制 0x02 按该响应的音频块顺序解码并排队播放。
response.audio.done 标记音频生成完成,继续播放剩余队列。
response.interrupted 停止播放并丢弃对应 response_id 的排队音频。

音频生成完成不代表用户已听完本地播放队列。单独跟踪实际播放进度。响应类型包括普通 chat、任务确认、进度、澄清和结果;保留未知类型标签,避免新增类型破坏基本播放。任务响应通过 turn_id 标识 Turn。常驻任务的结果是 task_result 类型的响应,其 Turn 没有对应的 task.accepted。口头任务确认不能证明任务完成;以 task.result 和普通 Session 的持久 Turn 结果为准。

跟踪每个 response_id 最后实际播放的音频块,而非最后收到的音频块。播放期间报告进度:

{ "type": "playback.progress", "response_id": "<response-id>", "chunk_index": 3 }

用户打断或点击停止时,立即停止本地播放并丢弃排队音频。如果知道实际播放的音频块,报告停止的响应:

{
"type": "playback.stopped",
"response_id": "<response-id>",
"chunk_index": 3,
"reason": "user_interrupt"
}

播放失败时使用 reason: error。索引非负,协议没有表示尚未播放音频的负数哨兵值。需要打断输出却不知道实际播放位置时,发送 { "type": "input_audio.clear" }。当前实现会打断服务提供方输出,不会删除已保存的 Session 转写。继续处理可能到达的 response.interrupted。即使服务器已经结束响应并忽略停止报告,本地停止的音频也保持停止。

客户端端点检测模式下,用户开始新一句话时,还要发送 input_audio.activity start,再发送新的麦克风音频。服务器端点检测使用服务提供方检测到的语音实现打断。两种模式都需要控制本地播放,因为客户端可能缓冲了服务器已经发送的音频。

设备控制下行节奏 (output_flow_control_v1)

Section titled “设备控制下行节奏 (output_flow_control_v1)”

不启用流控时,服务器按模型生成速度下发回复音频,长回复到达的速度可能远快于播放速度。下行为 Opus 的内存受限设备,可以改由自身容量和播放进度控制下发节奏。在首帧中请求该能力:

{
"type": "session.connect",
"connect_token": "<connectToken>",
"capabilities": ["output_flow_control_v1"]
}

capabilities 包含 1 到 8 个名称,每个最多 64 个字符;未知名称会被忽略。首帧携带 capabilities 时,session.ready 回显被接受的子集,可能为空。只有接受流控时,它才同时携带 "output_flow_control": { "flow_epoch": 12 }。服务器只对下行编码为 opus 的连接接受 output_flow_control_v1。每个 WebSocket(包括重连)都重新协商,客户端以本次 session.ready 返回的 flow_epoch 为准。数值只保证在同一运行实例内递增;跨进程恢复时可能重复。每次连接都必须丢弃客户端旧的 credit 和排空状态,重新授予容量。服务器也丢弃旧 WebSocket 的计数、排队音频和排空状态,其音频不会重放。不请求该能力的客户端仍使用未启用流控的发送路径。

在此能力之前部署的服务器会拒绝未知的 capabilities 字段:首帧以 invalid_event 失败,WebSocket 被关闭。先部署服务器,并且只向确认支持该能力的服务器请求它。

收到 session.ready 后,用累计 credit 报告设备的下行额度。同一 epoch 的第一条 credit 是容量 C,单位为音频包;之后的 credit 发送 C + released,其中 released 是设备已解码或已丢弃的包数:

{ "type": "audio.output.credit", "flow_epoch": 12, "grant_total_frames": 170 }

grant_total_frames 是 0 到 2147483647 的整数。重复或乱序的 credit 无害,以最大值为准;其他 epoch 的 credit 会被忽略。释放进度变化时发送 credit,例如最多每 50 ms 一次,不要让排队的麦克风音频延误它。未启用流控的 WebSocket 会忽略 credit 和排空事件。

流控生效时,服务器按以下规则发送音频:

  • 收到第一条 credit 之前不发送回复音频,其他事件照常发送。
  • 交给 WebSocket 的音频包总数不超过 grant_total_frames,仍在网络缓冲区中的包也计算在内。
  • 已发送但设备尚未释放的包最多 20 个(400 ms)。缺少 credit 时停止继续发送;服务器不会仅凭经过的时间推断设备已播放。
  • 每个响应开头最多连续发送 6 个包,之后平均每 20 ms 发送一个包。
  • 同一时间只播放一个响应。下一个 response.started 要等上一个响应排空或被打断后才发送。response.audio.done 在该响应最后一个包之后发送。转写、任务、用量、会话和错误事件不受影响。

响应完整播放后报告:

{
"type": "audio.output.drained",
"flow_epoch": 12,
"response_id": "<response-id>",
"last_chunk_index": 149
}

在收到 response.audio.done,且该响应的压缩队列、解码后的 PCM 和音频输出缓冲全部为空后发送。没有音频的响应省略 last_chunk_index。其他 epoch 或未知响应的排空事件会被忽略。继续用 playback.progress 报告实际播放到的音频块,response.audio.done 之后也一样。

用户打断会取消服务器仍为该 WebSocket 保留的全部下行输出,包括已经生成完毕的响应。打断包括 user_interrupt 原因的 playback.stopped、input_audio.clear 和服务提供方检测到的语音打断。未发送的包会被丢弃。已发送 response.started 的响应会收到 response.interrupted,位置为它最后报告的音频块;尚未宣布的响应被静默丢弃。reason: error 的 playback.stopped 只取消它指定的响应。打断从不重置 credit 计数:在下一条 credit 中把丢弃的包计为已释放。

每个连接最多保留 1500 个未发送的包(30 秒)、256 KiB 未发送音频和 8 个响应。将超出上限的生成会像播放失败一样被取消:丢弃其未发送音频;若响应已开始,随后发送 response.interrupted,并发送可恢复的 output_backlog_exceeded 错误,连接仍可使用。音频也可能只在等待设备:等待 credit、领先窗口或排空。处于这种状态时,如果 5 秒内没有收到任何 credit、排空事件或 playback.progress,服务器发送不可恢复的 output_flow_stalled 错误,并以 session.ended 原因 server 结束 Realtime Connection。

WebSocket 意外关闭时停止本地播放。要恢复,让后端为已有活跃 Realtime Connection 签发新授权:

终端窗口
curl -X POST 'https://<your-agent-service-host>/api/v1/user/sessions/<session-id>/realtime/connect-tokens' \
-H 'Authorization: Bearer <user-api-key>'

201 响应包含与首次打开时相同的三个授权字段。连接到其 websocketUrl,发送新的第一帧:

{
"type": "session.connect",
"connect_token": "<new-connectToken>",
"resume_after_event_id": "evt_42"
}

使用断线前最后收到的服务端 JSON event_id。二进制音频块没有事件 ID。在 60 秒恢复窗口内使用有界退避重试。token 的 60 秒有效期是另一个计时,不会延长恢复窗口。同一 Realtime Connection 上更新的 WebSocket 会替代之前的 WebSocket。

当前重放缓冲区只保留所属进程已捕获的 task.accepted、task.status 和 task.result,保留 60 秒。session.ready 之后重放的任务事件,ID 可能低于这条新 ready 事件。按事件标识去重,但仍处理此前没见过的重放事件,不要因为编号低于 ready 就丢弃。音频、转写和响应事件只实时发送。清空本地音频队列,不要重发服务提供方可能已经收到的麦克风音频。

WebSocket 断开期间,TaskBridge 停止转发任务事件,所以断线期间产生的通知即使在同一进程重连,也可能不在缓冲区中。重连后读取持久 Session/Turn 状态来恢复任务进度和结果。重放是补充交付方式,不是完整离线恢复。

同进程重连保留服务提供方会话与运行任务。跨进程接管会阻止旧服务提供方所有者继续产生效果,但目前不会重建进程内重放缓冲区或活跃任务订阅。从 Session Timeline恢复持久文字。跨进程丢失后的完整音频重放和任务恢复不属于本次基础契约。

要结束而非恢复,在就绪的 WebSocket 上发送 { "type": "session.end" },或由后端调用:

终端窗口
curl -X DELETE 'https://<your-agent-service-host>/api/v1/user/sessions/<session-id>/realtime' \
-H 'Authorization: Bearer <user-api-key>'

DELETE 返回已结束的 realtimeConnection,对最新连接已经结束的情况具有幂等性。正常的本地 WebSocket 结束会发送带原因的 session.ended,然后以代码 1000 关闭;收到此事件后停止重连。WebSocket 丢失或另一副本执行结束时,通过 GET …/realtime 确认终态,不要依赖收到该事件。仅关闭浏览器标签页会让连接在恢复窗口内继续可用。删除普通 Session 也会结束其 Realtime Connection,并使尚未使用的连接 token 失效。

模板可以为每次语音对话保持一个 Full Agent 任务持续运行,让设备驱动的 Agent 在用户开口之前就能行动和说话。设置可选内容字段 standingTask,例如 {"goal": "通过展台 Connector 等待戳碰传感器触发,然后用一句话说明发生了什么。"}。目标会去除首尾空白,长度为 1 到 4000 个字符(按 UTF-16 代码单元计数)。它只在基于已开启语音的模板创建的 Session 的 Realtime Connection 中生效;realtime: null 时会保存但不生效,Template Playground 会忽略它。

客户端已连接且没有由语音发起的任务时,服务保持一个使用该目标的 Turn 运行。第一个 Turn 在 WebSocket 连接后启动,而不是在打开连接时启动。它以非空回复完成时,Realtime Model 会在用户空闲后简要说明该回复,对应一个类型为 task_result、带 turn_id 的 response.started。空回复、澄清、失败或取消都不会播报。随后启动下一个 Turn。相邻启动至少间隔一秒,失败后退避;一分钟内启动 20 次后暂停一分钟。

语音请求会抢占常驻任务:服务取消常驻 Turn,在短暂且有上限的等待其结束后启动用户要求的任务。偶尔被取消的 Turn 仍占用 Session,此时用户要求的任务会被拒绝,需要用户再次提出。该任务出结果后常驻任务自动恢复。它不发送 task.* 事件。断开 WebSocket 或结束连接通常会取消它,重连后启动新的常驻任务。凭证失效导致的结束会保留已经接受的常驻 Turn,并停止后续轮次。常驻 Turn 运行期间在 Session 中输入的文字会并入该 Turn,其回复会被播报。用户打断可能丢弃等待播报的回复,且不会重复播报。

每一轮都是 Session 中一个持久且计费的 Turn。其用户消息以目标为文本,inputContext.channel 为 standing_task,客户端可以将它与用户输入或说出的内容区分显示。目标应优先等待事件(例如长轮询的 Connector 工具),而不是轮询。

REST 失败使用客户 ErrorEnvelope。WebSocket 失败使用 JSON error 事件,包含 code、message 和 recoverable。可选客户端 event_id 会在关联错误的 client_event_id 中回传。握手前错误使用服务端 event_id: evt_0。同时处理错误事件和 WebSocket 关闭,因为已经断开的 WebSocket 不能传递错误。

失败 恢复方式
REST 401 authentication_required 或 403 user_api_key_required 修正后端凭据。这些路由接受所属 User Key,不接受浏览器 Session 或 Organization Key。
REST 404 session_not_found 使用已有、归该用户所有且未删除的 Session。
REST 409 session_read_only 选择可以继续交互的 Session。
REST 409 realtime_connection_live 读取并恢复活跃连接,或明确结束它再打开新连接。
token 签发时 REST 404 realtime_connection_not_found 或 409 realtime_connection_ended 读取 Session 状态,Session 可用时再打开新 Realtime Connection。
REST 400 audio_format_unsupported 依据 error.details 修正请求方向的格式。
REST 503 admission_unavailable 接纳依赖暂时不可用。退避重试;重复打开前先读取连接状态,因为签发 token 失败前可能已成功接纳连接。
WS invalid_connect_token 为正确 Session 获取新授权,不重用被拒绝的 token。
WS endpointing_unsupported 选择支持的模式;更新被拒绝时保留当前模式。
WS invalid_event 修正事件形状、帧或发送顺序。重复无效帧会导致关闭。
WS output_backlog_exceeded 设备消耗音频不够快,流控取消了一个回复。WebSocket 仍可使用;检查 credit 报告。
WS output_flow_stalled 音频等待期间流控反馈中断,Realtime Connection 已结束。修正 credit 和排空报告后打开新连接。
WebSocket 升级返回 429 服务器暂时拒绝新的 WebSocket。以有界退避重试;token 未被消耗。
WS 不可恢复错误,例如 provider_unavailable 或 session_expired 停止在该 WebSocket 上发送,读取 REST 连接状态,再决定是否重新打开。

重复无效帧也可能以标准代码 1008 关闭 WebSocket。可恢复错误保持 WebSocket 可用,不表示应该重放音频或重复任务请求。已终止的 Realtime Connection 需要重新打开,不能仅签发另一个 token。

本指南覆盖语音传输和 Full Agent 任务委托。用户要求的设备动作和状态读取由 Realtime Model 调用 start_task 完成,简单物理动作也一样。普通语音任务 Turn、关联的澄清续接和常驻任务 Turn 与文本 Turn 一样,冻结 Session 当前的 Client Tools。它们的调用与文本 Turn 一样,以 tool.call 发给你的应用在 Backend Connection 上的执行挂接(executing attachment),使用真实 Turn/Run 身份及已有期限和权限复查。Realtime 不提供直接设备工具或指令/结果帧。Template Test 通过不接纳 Client Tools 的 Full Agent Turn 委派任务。Session 历史载入、完整语音与文字任务引导,以及跨进程恢复仍有实现缺口。设备激活、OTA、MQTT/UDP 和物理执行由你的应用负责。

在 tidb-link.realtime.v1 中,新增事件和可选字段属于兼容扩展,客户端应容忍未知的服务端事件类型和字段。删除事件或改变事件含义需要新的子协议版本,但有一项明确的撤销例外:已取消的直接设备路径在 v1 中移除 device.command、device.command_result 和活跃的 device_ack。已有客户端必须停止发送设备结果,并通过 Full Agent 任务委托执行设备工作。已持久化的历史 device_ack 时间线记录仍可读取,不代表支持活跃帧。

Realtime Connection 在连接期间通过用量 API报告用量,通常最多比实际消耗晚 60 秒,结束时再报告一次。每次报告是一条用量记录,包含 requestPurpose: voice_realtime、sessionId、realtimeConnectionId、值为 null 的 turnId,以及自上次报告以来的用量,时间为其覆盖区间的结束时间。因此同一连接的记录互不重叠,连接结束后合计等于其结算用量;跨越 UTC 月份边界的连接在每个月只计入当月的用量。明细读取中的 realtimeConnectionLive 表示该记录所属的连接是否仍在进行。每次报告按报告时该连接 Realtime 模型的平台销售价计价。没有对应售价时成本为 null,原因写在 valuationReason 中,例如 no_active_sale_price;未知成本不代表零成本。

Template Playground 可以基于完整冻结的 Test 内容以及分别选择的 Full Agent 和 Realtime 模型测试语音。两项选择在整个 Test 期间固定;更换任一模型都需要新建 Test。结束通话会保持 Test 开放,重新连接仍使用已选模型。不可用的选择保持可见,不会自动切换到其他模型。如果 Test 开始时尚未发布实时模型,需要在模型可用后新建 Test。Playground 不接纳 Client Tools 和 Connector,私有文件仍不可用;其语音任务会调用 Template 的 MCP 服务器,详见 MCP 服务器。客户应用通过本指南的 User Key 路由接入普通 Session。

GET /api/v1/user/sessions/{id}/turns 和 /turns/{turnId} 也会返回已记录的语音交流,标记为 executor: realtime_model;普通执行 Turn 返回 executor: full_agent。Realtime Turn 包含 audio userMessage、userMessages 中的全部定稿输入转写、可选的 assistant 转写、status: succeeded 和空 Operations,不返回 completedAt。可选的 realtime 元数据标识 Connection 及关联的 Full Agent Turn。Message 元数据保留回复类型、任务关联和打断标记;被打断的转写可能包含用户没有听到的内容。

没有用户输入的回复属于纯播报。它自己的 Turn 不出现在列表中,按 ID 查询返回 404 turn_not_found。有关联任务的回复放在该 Full Agent Turn 的可选 realtimeResponses 中;无关联的问候仍可从 /timeline 读取。Realtime Turn 不启动执行、不改变 activeTurnId、不创建命令回执,也不发送 Full Agent Turn 生命周期事件。语音用量仍归属于 Connection。

Turn 分页按创建时间和 Turn ID 排序。Realtime 记录在交流结束后写入,但保留开始时间,因此已推进的 cursor 可能永久漏过迟写的记录。要恢复这些记录,需从头刷新列表;需要按持久事件序号重放时使用 /timeline。Timeline 返回结构和 agent.session.realtime.* SSE 事件格式保持不变。缺少 timeline 记录的旧 VoiceTurn 不纳入。Full Agent 模型上下文及上下文压缩会纳入已记录的语音,包括纯播报、回复类型和打断标记。语音任务开始前最多等待一秒,让本连接此前的交流先完成记录,因此任务上下文通常包含这些交流;超过一秒仍未记录的交流可能不在该任务的上下文中。发起任务的那轮交流在之后才记录,任务直接收到这次请求。语音转写是不可信的对话数据,不是任务已完成的证明。Session Recall 仍需单独接入。

完整语音交流记录后,尚无名称或自动标题的普通 Session 可以获得 autoTitle。生成在后台进行,不覆盖手动重命名。Template Test 和纯播报不触发自动标题。标题请求单独产生 auto_title 用量,归属于触发它的 Realtime Turn;语音用量仍归属于 Connection。