date: "2026-07-24"
快速发起语音通话
本文档用于说明如何快速调用 AI Agent 相关后台接口实现与 AI Agent 的语音互动。
实现数字人视频通话
数字人介绍
实现数字人实时播报
与数字人视频通话的区别
前提条件
- 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 ServerSecret（用于服务端 API 签名与 RTC Token04 生成），详情请参考 控制台 - 项目信息。
- 已在 ZEGO 控制台 开通了实时互动 AI Agent 服务
- 已获取了 LLM 和 TTS 相关配置信息。，详细请参考 控制台 - 实时互动 AI Agent。
- 已获取有效的 digital_human_id（测试时可使用公共 ID：c4b56d5c-db98-4d91-86d4-5a97b507da97）。
在接入测试期间(AI Agent 服务开通 2 周内)，可以将 LLM 和 TTS 的鉴权参数设置为 "zego_test" 即可使用相关服务。具体鉴权参数配置请参考注册智能体 > BODY 参数说明。
同时可自行采购ZEGO支持LLM、TTS服务并获取鉴权信息使用。也可通过联系ZEGO商务直接采购TTS服务。
示例代码
以下是接入实时互动 AI Agent API 的业务后台示例代码，您可以参考示例代码来实现自己的业务逻辑。
包含最基本的获取 ZEGO Token、注册智能体、创建智能体实例、删除智能体实例等能力。
以下是客户端示例代码，您可以参考示例代码来实现自己的业务逻辑。
包含最基本的登录、推流、拉流、退出房间等能力。
包含最基本的登录、推流、拉流、退出房间等能力。
包含最基本的登录、推流、拉流、退出房间等能力。
包含最基本的登录、推流、拉流、退出房间等能力。
以下视频演示了如何跑通服务端和客户端（Web）示例代码并跟智能体进行语音互动。
整体业务流程
- 服务端，跑通业务后台示例代码，部署好业务后台
- 接入实时互动 AI Agent API 管理智能体。
- 客户端，参考 Android 端快速开始 、 iOS 端快速开始 或 Web 端快速开始 文档跑通客户端示例代码
- 通过业务后台创建和管理智能体。
- 集成 ZEGO Express SDK 完成实时通信。
完成以上两个步骤后即可实现将智能体加入房间并与真实用户进行实时互动。
核心能力实现
注册智能体
注册智能体 用于设定智能体基础配置，包括智能体名称、LLM、TTS、ASR等相关配置。注册后可以将该智能体作为模板创建多个实例与多个真实用户进行互动。
通常智能体是相对比较固定的，一旦设定好智能体的相关参数（人设形象）就不会经常改动。所以建议按照业务流程需要在适当时机注册智能体即可。智能体注册后不会自动销毁和回收，创建智能体实例后即可与该智能体进行语音交互。
以下是调用注册智能体接口的示例：
// 请将以下示例中的 LLM 和 TTS 的 ApiKey、appid、token 等鉴权参数换成你实际的鉴权参数。
async registerAgent(agentId: string, agentName: string) {
// 请求接口：https://aigc-aiagent-api.zegotech.cn?Action=RegisterAgent
const action = 'RegisterAgent';
const body = {
AgentId: agentId,
Name: agentName,
LLM: {
Url: "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
ApiKey: "zego_test",
Model: "doubao-1-5-pro-32k-250115",
SystemPrompt: "你是一个智能体，请根据用户的问题回答。"
},
TTS: {
Vendor: "ByteDance",
Params: {
"app": {
"appid": "zego_test",
"token": "zego_test",
"cluster": "volcano_tts"
},
"audio": {
"voice_type": "zh_female_wanwanxiaohe_moon_bigtts"
}
}
}
};
// sendRequest 方法封装了请求的 URL 和公共参数。详情参考：/aiagent-server/api-reference/accessing-server-apis
return this.sendRequest<any>(action, body);
} - 请确保 LLM 所有参数都按照 LLM 服务提供商官方文档填写正确，否则您可能无法看到智能体回答的文本内容也无法听到智能体输出语音。
- 请确保 TTS 所有参数都按照 TTS 服务提供商官方文档填写正确，否则您可能可以看到智能体回答的文本内容却无法听到智能体输出语音。
- 如遇智能体无法输出文本内容或语音，请先检查 LLM 和 TTS 参数配置是否完全正确，或参考 获取智能体服务状态 - 监听服务端异常事件 确定具体的问题。
创建智能体实例
可以用已注册的智能体为模板 创建多个智能体实例 加入不同房间与不同用户进行实时互动。创建智能体实例后，智能体实例会自动登录房间并推流，同时也会拉真实用户的流。
创建智能体实例成功后，真实用户在客户端监听流变化事件并拉流就可以与智能体进行实时互动了。
以下是调用创建智能体实例接口的示例：
async createAgentInstance(agentId: string, userId: string, rtcInfo: RtcInfo, messages?: any[]) {
// 请求接口：https://aigc-aiagent-api.zegotech.cn?Action=CreateAgentInstance
// const rtcInfo = {
// RoomId: room_id,
// AgentStreamId: agent_stream_id,
// AgentUserId: agent_user_id,
// UserStreamId: user_stream_id,
// };
const action = 'CreateAgentInstance';
const body = {
AgentId: agentId,
UserId: userId, // 与该 AIAgent 实例交互的真实用户 ID
RTC: rtcInfo,
MessageHistory: {
SyncMode: 1, // Change to 0 to use history messages from ZIM
Messages: messages && messages.length > 0 ? messages : [],
WindowSize: 10
}
};
// sendRequest 方法封装了请求的 URL 和公共参数。详情参考：/aiagent-server/api-reference/accessing-server-apis
const result = await this.sendRequest<any>(action, body);
console.log("create agent instance result", result);
// 在客户端要保存返回的 AgentInstanceId ，用于后续删除智能体实例。
return result.AgentInstanceId;
} 完成这一步骤后，您就可以创建智能体实例。集成客户端后可与该智能体实例进行语音互动。
集成客户端 SDK
请参考以下文档完成客户端的集成开发：
快速开始
快速开始
快速开始
快速开始
恭喜您🎉！完成这一步骤后，您已经成功集成客户端 SDK 并可以与智能体实例进行实时语音互动了。您可以用语音问智能体任何问题，智能体都会回答您的问题！
删除智能体实例
删除智能体实例后，智能体实例会自动退出房间并停止推流。真实用户在客户端停止推流和退出房间后，一次完整的互动就结束了。
以下是调用删除智能体实例接口的示例：
async deleteAgentInstance(agentInstanceId: string) {
// 请求接口：https://aigc-aiagent-api.zegotech.cn?Action=DeleteAgentInstance
const action = 'DeleteAgentInstance';
const body = {
AgentInstanceId: agentInstanceId
};
// sendRequest 方法封装了请求的 URL 和公共参数。详情参考：/aiagent-server/api-reference/accessing-server-apis
return this.sendRequest(action, body);
} 以上就是您实现与智能体进行实时语音互动的完整核心流程。
监听回调
点击查看监听回调指引。监听回调中 Event 为 Exception 的事件。通过 Data.Code 和 Data.Message 可以快速定位问题。
点击查看异常错误码列表。