logo
当前页

快速发起语音通话

2026-02-05

本文档用于说明如何快速集成客户端 SDK (ZEGO Express SDK)并实现与智能体进行语音互动。

前提条件

示例代码

以下是接入实时互动 AI Agent API 的业务后台示例代码,您可以参考示例代码来实现自己的业务逻辑。

以下是客户端示例代码,您可以参考示例代码来实现自己的业务逻辑。

以下视频演示了如何跑通服务端和客户端(Web)示例代码并跟智能体进行语音互动。

整体业务流程

  1. 服务端,参考业务后台快速开始文档跑通业务后台示例代码,部署好业务后台
    • 接入实时互动 AI Agent API 管理智能体。
  2. 客户端,跑通示例代码
    • 通过业务后台创建和管理智能体。
    • 集成 ZEGO Express SDK 完成实时通信。

完成以上两个步骤后即可实现将智能体加入房间并与真实用户进行实时互动。

核心能力实现

集成 ZEGO Express SDK

请参考 集成 SDK 集成 SDK 后按以下步骤初始化 ZegoExpressEngine。

1 实例化 ZegoExpressEngine

2 检查系统要求(WebRTC 支持和麦克风权限)

import { ZegoExpressEngine } from "zego-express-engine-miniprogram";

const appID = 1234567 // 从即构控制台获取
const server = 'xxx' // 从即构控制台获取的 Server 地址

// 实例化 ZegoExpressEngine 传入 appId 和 server 等配置
// !mark
const zg = new ZegoExpressEngine(appID, server);
// 初始化小程序组件实例
zg.initContext({
  wxContext: context,
  pushAtr: "pusher", // pushAtr 配置的变量名,必须与传给 <zego-pusher> 组件 pusher 属性的变量名完全一致。
  playAtr: "playerList" // playAtr 配置的变量名,必须与传给 <zego-player> 组件 playerList 属性的变量名完全一致。
})

// 检查系统要求
// !mark
const checkSystemRequirements = async () => {
  const rtc_sup = await zg.checkSystemRequirements();
  if (res.code === 10002) {
    // 未开启麦克风权限
  }
  if (res.code === 10001) {
    // 当前微信版本过低,无法使用相关组件
  }
}
checkSystemRequirements()

创建对应业务场景的 WXML

  1. 复制组件代码到项目工程中

将示例代码 components 文件夹下的 zego-player 和 zego-pusher 两个文件夹,复制到您的业务代码 components 文件夹中。

  1. 在项目 JSON 文件中引入组件

根据您的项目结构,在对应的 JSON 文件中引入 <zego-pusher><zego-player> 组件。

// 在 JSON 文件中引入组件
{
  "usingComponents": {
    "zego-pusher": "../../components/zego-pusher/zego-pusher",
    "zego-player": "../../components/zego-player/zego-player"
  }
}

在 WXML 文件中使用推拉流组件

在 WXML 文件中使用推拉流组件 <zego-pusher><zego-player>

// 在 WXML 文件中使用组件
// 传给 <zego-pusher> 组件 pusher 属性的变量名,必须与 initContext 配置中 pushAtr 的参数值完全一致。
  <zego-pusher id="zegoPusher" pusher="{{pusher}}" />
// 传给 <zego-player> 组件 playerList 属性的变量名,必须与 initContext 配置中 playAtr 的参数值完全一致。zegoPlayerList 见 “拉取其他用户的音频” 章节。
  <zego-player wx:for="{{zegoPlayerList}}" wx:key="id" id="{{item.componentID}}" playerId="{{item.playerId}}" playerList="{{playerList}}" />

通知业务后台开始通话

可在客户端真实用户进入房间后立即通知业务后台开始通话,异步调用可加降低通话接通时间。业务后台收到开始通话通知后,使用与客户端相同的 roomID 及关联的 userID 和 streamID 创建智能体实例,这样智能体就能与真实用户在同一个房间内进行相互推拉流实现语音互动。

注意
默认情况下一个账号下最多同时存在 10 个智能体实例,超过限制后创建智能体实例会失败,如需调整请联系 ZEGO 商务。
说明
以下示例在通知业务后台开始通话时,并没有传递 roomID、userID、streamID 等参数,是因为本示例客户端与业务后台约定好了固定值。实际使用时,请根据业务需求传递对应的参数。
// 通知业务后台开始通话
async function startCall() {
  try {
    // 后台在/api/startn接口中实际调用createAgentInstance接口
    // !mark
    const response = await fetch(`${YOUR_SERVER_URL}/api/start`, { // YOUR_SERVER_URL 为您的业务后台地址
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      }
    });

    const data = await response.json();
    console.log('开始通话结果:', data);
    return data;
  } catch (error) {
    console.error('开始通话失败:', error);
    throw error;
  }
}

用户进入房间并推流

真实用户登录房间后推流。

登录用的 token 需要从您的业务后台获取,请参考完整示例代码。

说明

请确保 roomID、userID、streamID 在一个 ZEGO APPID 下是唯一的。

  • roomID: 由用户自己定义生成规则,会用来登录 Express SDK 的房间。仅支持数字,英文字符 和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''。如果需要与 Web SDK 互通,请不要使用 '%'。
  • userID: 长度不超过32字节。仅支持数字,英文字符 和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''。如果需要与 Web SDK 互通,请不要使用 '%'。
  • streamID: 长度不超过256字节。仅支持数字,英文字符 和 '-', '_'。
客户端登录房间并推流
const userId = "" // 登录 ZEGO Express SDK房间用户ID
const roomId = "" // RTC 房间 ID
const userStreamId = "" // 用户推流 ID
async function enterRoom() {
  try {
    // 生成 RTC Token [参考文档](/real-time-video-web/communication/using-token-authentication)
    const token = await Api.getToken();
    // 登录房间
    await zg.loginRoom(roomId, token, {
      userID: userId,
      userName: "",
    });

    // 创建本地音频流
    const zegoPusher = this.selectComponent("#zegoPusher");
// !mark(1:2)
    // 推送本地流
    await zegoPusher.startPush(zg, userStreamId, {}, {enableCamera: false, mode: 'RTC'});
  } catch (error) {
    console.error("进入房间失败:", error);
    throw error;
  }
}
enterRoom()

拉智能体流

默认只有一个真实用户及智能体在同一个房间内,所以拉流时默认新增的就是智能体流。

客户端拉智能体的流
// 监听远端流更新事件
function setupEvent() {
  zg.on("roomStreamUpdate",
    async (roomID, updateType, streamList) => {
      if (updateType === "ADD" && streamList.length > 0) {
        try {
          for (const stream of streamList) {
            // 设置 zego-player 组件属性
            const zegoPlayerAttr = {
              componentID: `zego-${stream.streamID}`,
              playerId: stream.streamID
            };
            // 更新,并渲染组件列表
            this.setData({
              zegoPlayerList: this.data.zegoPlayerList
            })
            const zegoPlayer = wxContext.selectComponent(`#${zegoPlayerAttr.componentID}`);
            if (zegoPlayer) {
// !mark
              await zg.startPlayingStream(zegoPlayer, stream.streamID);
            }
          }
        } catch (error) {
          console.error("拉流失败:", error);
        }
      }
    }
  );
}

恭喜你🎉!完成这一步骤后,您已经可以用语音问智能体任何问题,智能体都会用语音回答您的问题!

退出房间结束通话

客户端调用退出登录接口退出房间,并停止推拉流。同时通知业务后台本次通话结束。业务后台收到结束通话通知后会删除智能体实例,智能体实例会自动退出房间并停止推拉流。这样一次完整的互动就结束了。

// 退出房间
async function stopCall() {
  try {
// !mark
    const response = await fetch(`${YOUR_SERVER_URL}/api/stop`, { // YOUR_SERVER_URL 为您的业务后台地址
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      }
    });

    const data = await response.json();
    console.log('结束通话结果:', data);
    return data;
  } catch (error) {
    console.error('结束通话失败:', error);
    throw error;
  }
}
stopCall();
zg.stopPublishingStream();
if (zegoPlayerList.length) {
  for (const player of zegoPlayerList) {
    zg.stopPlayingStream(player.playerId);
  }
}
// !mark
zg.logoutRoom();

以上就是您实现与智能体进行实时语音互动的完整核心流程。

ZEGO Express SDK 最佳配置实践

为了获得最佳的音频通话体验,建议按照以下最佳实践配置 ZEGO Express SDK。这些配置可以显著提升智能体语音交互的质量。

  • 推流时,设置推流模式为 RTC
// 引入必要的模块
import { ZegoExpressEngine } from "zego-express-engine-webrtc";

// 实例化 ZegoExpressEngine
const zg = new ZegoExpressEngine(appID, server);

// 创建本地音频流
const zegoPusher = this.selectComponent("#zegoPusher");
// 推送本地流
// !mark
await zegoPusher.startPush(zg, userStreamId, {}, {enableCamera: false, mode: 'RTC'});

// 检查系统要求
const checkSystemRequirements = async () => {
  const rtc_sup = await zg.checkSystemRequirements();
  if (res.code === 10002) {
    // 未开启麦克风权限
    return false;
  }
  if (res.code === 10001) {
    // 当前微信版本过低,无法使用相关组件
    return false;
  }
  return true;
}

监听异常回调

注意
由于 LLM 和 TTS 等参数比较多且复杂,在接入测试过程中容易因为参数配置错误导致的智能体不回答或者不说话等各种异常问题。我们强烈建议您在接入测试过程中监听异常回调,并根据回调信息快速排查问题。
2026-02-05

上一篇

发布日志

下一篇

展示字幕