语音智能体接入:回调、播报与打断
以 XingyunAvatarAgent 为例,梳理初始化、语音回调、流式展示与会话状态。
“模型已经输出完了,页面能显示本轮结束吗?”
接语音智能体时,这个问题很容易被低估。一次问答至少包含请求发送、模型生成、语音与动作表达几个过程。把其中任意一步当作整轮结束,都可能让界面状态提前变化。
还有两个常见问题:ASR 已经自动进入对话,业务又提交了一次相同文本;页面离开后,会话或麦克风资源没有及时释放。
本文使用魔珐星云的 XingyunAvatarAgent 端到端 SDK 作为接入示例,重点讨论这些状态与事件如何处理。示例依据 SDK 文档整理,不包含真实设备上的延迟、识别率或自然语音打断测试,也不把文档能力等同于实测结果。
阅读前先确定边界
本文的示例运行在 Web 中,涉及文本问答、语音输入、回复展示、客户端打断和会话销毁。视觉感知、机器人运动控制、跨终端记忆同步,需要各自的设备与业务接入,不会因为这段 Web 代码运行成功而自动具备。
如果想从头跟着本文体验,也可以通过我的专属链接进入魔珐星云,在注册页面填写:
邀请码:JSUAY3IS96
快速开始:https://media.xingyun3d.com/learning/index.html
01 先让它开口:换到新的 Agent 入口
如果你之前接过旧版 XmovAvatar,应该熟悉这种分工:业务拿到 ASR 的识别结果,交给大模型,再把回复拼成 SSML,调用 speak()。
到了新版 XingyunAvatarAgent,文本对话和语音输入都有了对应入口。我们先准备一个有明确尺寸的容器,再引入端到端 SDK:
<div id="avatar"
style="width:100%;height:520px"></div>
<button id="start-asr">开始语音</button>
<button id="stop-asr">停止收音</button>
<button id="interrupt">打断表达</button>
<button id="destroy">结束会话</button>
<p id="asr-text"></p>
<p id="answer-text"></p>
<p id="conversation-state"></p>
<script src="https://media.xingyun3d.com/xingyun3d/general/litesdk/xmovAvatar_e2e@latest.js"></script>
下文的 JavaScript 可放在这些节点之后的 <script type="module"> 中,以使用顶层 await。先在平台侧准备好角色、音色及智脑等应用配置,再替换下面的 appId、appSecret。示例用于接入验证,真实凭据不要提交到公开仓库;生产环境按项目的鉴权方案处理。
const agent = new window.XingyunAvatarAgent({
container: document.getElementById("avatar"),
appId: "your-app-id",
appSecret: "your-app-secret",
gatewayServer:
"https://nebula-agent.xingyun3d.com" +
"/user/v1/ttsa_v2/session",
enableClientInterrupt: true,
onMessage(error) {
console.error("渲染层", error.code, error.message);
},
agentCallbacks: {
onError(error) {
console.error("Agent 层", error.code, error.message);
},
},
});
这里先圈出三个容易漏掉的地方:加载的是 xmovAvatar_e2e@latest.js;全局对象换成 XingyunAvatarAgent;网关路径换成了 /ttsa_v2/session。
还有错误监听。新版除了渲染层的 onMessage,还要关注 agentCallbacks.onError,ASR、Brain、网络等环节的异常也需要进入排查视野。
接下来等初始化完成,再发起第一轮文本对话:
await agent.init({
onDownloadProgress(progress) {
console.log(`资源加载 ${progress.toFixed(0)}%`);
},
});
await agent.ask("请用两句话介绍这个展厅。");
ask() 把输入交给智脑,再进入具身表达链路。应用侧不用再为这次回复额外调用一遍 speak()。
但先别把 await agent.ask() 理解成“它已经说完”。调用成功与整轮表达结束,是后面要分开看的两个时刻。

图 1|完成初始化后,分别通过文本和语音入口发起交互。
02 打开麦克风,最该少写的一行代码
文本对话跑通后,再接语音会更容易定位问题。
const startButton = document.getElementById("start-asr");
const stopButton = document.getElementById("stop-asr");
startButton.addEventListener("click", async () => {
try {
await agent.startASR();
} catch (error) {
console.error("语音启动失败", error);
}
});
stopButton.addEventListener("click", async () => {
try {
await agent.stopASR();
} catch (error) {
console.error("停止识别失败", error);
}
});
页面需要运行在 HTTPS 或 localhost,麦克风由用户点击按钮后开启。按钮是否可用,应结合初始化进度、Agent 与 ASR 状态来控制。
这一步有个很容易顺手写出来的问题:在 onASRResult 收到最终识别结果后,又手动执行一次 agent.ask(result.text)。
在默认自动对话链路里,识别完成后会自动进入智脑对话。识别回调可用于字幕展示或调试,重复 ask() 可能把同一句话提交两遍。
这也解释了为什么新旧示例不能原样混用。旧项目里承担“向下一环传递结果”的业务代码,迁移之后要重新检查。
语音接入之后,可以在播报过程中插入一句:“先讲讲二号展区。”再分别观察识别文本、打断事件和下一轮回复。
这里要区分“麦克风正在收音”和“系统识别到了有效插话”。平台资料列出了降噪、AEC/抗回声、本体声音抑制、VAD、远场语音及 Double Talk/Barge-in 等能力;具体表现需要结合应用配置、音箱与麦克风的位置、环境噪声验证。仅调用 startASR(),不足以证明这些环节在当前设备上都已达到预期。
03 大模型输出完了,智能体还可能没说完
如果页面上有一个“本轮已结束”的提示,你会把它挂在哪个事件上?
只看大模型流式输出的 done,容易提前一步。文字已经生成完,语音和动作仍可能在继续。
这时需要把回调各自负责的事情分清楚。在创建实例之前,先获取用于展示的节点:
const asrText = document.getElementById("asr-text");
const answerText = document.getElementById("answer-text");
const conversationState =
document.getElementById("conversation-state");
再把下面这些方法加入构造参数中的 agentCallbacks,与前面的 onError 一起使用:
onASRResult(result) {
asrText.textContent = result.text;
// 默认自动对话模式:此处不重复 ask()
},
onLLMResponse(response) {
if (response.event === "chunk") {
if (response.isFirst) answerText.textContent = "";
answerText.textContent += response.text ?? "";
}
// done 表示模型输出结束,不据此宣布播报结束
},
onConversationChange(event) {
conversationState.textContent = event.state;
if (event.state === "completed") {
console.log("本轮播报已结束");
}
},

图 2|事件语义示意,间距不代表耗时;真实执行中,模型输出与表达可以重叠。
另外,onAgentStateChange 适合观察整体状态,onASRStateChange 适合观察麦克风与识别状态,onSocketStateChange 用来辅助定位 E2E 控制连接问题。
主动点击“打断”按钮时,可以调用:
const interruptButton = document.getElementById("interrupt");
const destroyButton = document.getElementById("destroy");
interruptButton.addEventListener("click", () => {
agent.interrupt("speak");
});
destroyButton.addEventListener("click", async () => {
try {
await agent.destroy("user");
} catch (error) {
console.error("会话释放失败", error);
}
});
结束交互时,调用 destroy() 释放会话与麦克风资源;如果集成在组件中,也应在卸载钩子里清理。按钮打断可以帮助检查客户端链路。自然语音插话能否及时被识别,还需要结合应用配置、拾音环境和有效打断判定来验证。
04 为什么要分开维护三种状态
把全部过程压成一个 isBusy,初期很省事,但不容易区分以下情况:
- Agent 连接正在恢复,当前不能接收新请求。
- 麦克风仍在收音,但当前表达已经被打断。
- 模型输出已结束,播报仍在继续。
因此,界面至少要分别观察 Agent 状态、ASR 状态和对话状态。它们有联系,也各自有不同的变化条件。
在平台的术语中,这类系统被称为“端到端具身交互智能”。官方将整体能力概括为:多模态感知 + 专属智脑 + 多模态表达 + AI 端渲 + 数字与物理行动。
端到端不是简单拼接,而是需要围绕同一次交互协调事件、会话状态、时序与异常。
这对应用开发的具体要求,是用户插话、模型生成、表达结束和网络重连之间,不能各自维护一份互不一致的状态。

图 3|平台交互模型的概念示意,不表示该 Web 示例已实现全部感知与行动能力。
“专属智脑”可以理解为知识、身份规则、任务与业务工具的配置层。RAG、知识图谱、工作流或企业系统是否实际参与回答,要看应用配置和调用结果;接通 ask() 本身并不能证明已经完成这些业务集成。
同样,AI 端渲描述的是渲染侧的工程安排,不能据此推断语音和智脑服务也可离线。一个智能体可以进入不同的身体,但跨终端复用身份、知识、任务和记忆,仍需要相应配置;机器人动作也取决于本体与已接入技能。
05 替换组件时,检查接口之外的行为
可插拔组件允许复用已有 ASR、模型或 TTS。集成时,接口能调用只是第一步,还要核对替换前后的事件语义。
| 模块 | 接入后应确认的行为 |
|---|---|
| ASR | 临时结果与最终结果如何区分;是否自动进入对话;如何上报识别失败 |
| Brain | 上下文如何传递;流式首块与结束事件如何表示;业务工具是否获得授权 |
| TTS 与表达 | 模型结束后是否仍在播报;如何通知表达完成;打断后是否残留旧内容 |
| 机器人运控 | 哪些动作由本体提供;失败与取消如何回传;是否存在实际执行权限 |
例如,替换 ASR 之后,如果继续沿用旧业务代码,在最终结果回调里手动 ask(),而新的链路又已自动提交,就会产生重复请求。这个问题与识别准确率无关,根源在于两个环节都承担了“提交到下一步”的职责。
平台文档描述的标准化接口契约与统一状态管理,需要在这些具体场景中核对:事件有没有重复、状态能不能恢复、取消动作是否生效、异常是否到达应用层。
06 用一组可观察的场景结束联调
不要只观察“能否回复第一句话”。下面这组场景更容易暴露会话问题,表中是检查目标,不是本文的实测结果。
| 操作 | 应观察的结果 |
|---|---|
| 初始化尚未完成时尝试提交 | 不应直接调用需要 running 状态的接口 |
| 语音说完一句完整问题 | 在自动对话模式下,不应因业务重复调用而产生两次相同请求 |
| 收到模型 done 事件 | 可以结束文本生成提示,不应直接冒充播报 completed |
| 开始下一轮回复 | 上一轮展示内容应按业务需要清空,避免错误拼接 |
| 点击客户端打断 | 当前表达应按 SDK 约定被停止,并能继续处理后续交互 |
| 模拟网络断开再恢复 | 状态提示、按钮可用性和 SDK 恢复状态应保持一致 |
| 退出页面或卸载组件 | 主动释放会话、麦克风及相关监听 |
自然语音打断还需要单独测试:用户插话、咳嗽、轻声应和、扬声器回声与背景噪声,不能只用一个按钮调用来代替验证。如果要比较方案,也应在相同设备、网络、音量和测试语料下记录结果。
这篇接入示例想留下的,是一个适用于多种语音智能体的判断方法:先明确每个事件表示哪一步完成,再决定页面状态和下一步动作。 请求提交成功、模型输出结束与播报结束,各有各的用途。
参考文档
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/m0_68089732/article/details/168345053




