2025/03/28 14:38:19
使用 RESTful API 实现对话式 AI 引擎
本文介绍如何调用声网对话式 AI 引擎 RESTful API 创建一个对话式智能体 (Conversation AI Agent)，并实现与 AI 智能体对话互动。
前提条件
开始前，请确保:
- 已参考开通服务在声网控制台完成以下步骤：
- 为你的项目开通声网对话式 AI 引擎。
- 获取 App ID：声网随机生成的字符串，用于识别你的项目和调用对话式智能体 RESTful API。
- 获取客户 ID 和客户密钥：用于在调用对话式 AI 引擎 RESTful API 时进行 HTTP 安全认证。
- 生成临时 Token：Token 也称为动态密钥，用于在加入 RTC 频道时对用户鉴权。临时 Token 的有效期为 24 小时。在生产环境中，你需要参考使用 Token 鉴权在你的 App 服务端生成 Token。
- 已参考实现音视频互动集成 v4.5.1 及以上版本的实时互动 SDK，并在你的 App 中实现基本的实时音视频功能。
信息
如果你想使用嵌入式智能硬件与 AI 智能体对话，你可以集成 1.9.x 及以上版本的 RTSA C SDK，并参考实现媒体流和信令传输在你的设备端实现基本的实时音视频功能。
- 已获取大语言模型 (LLM) 供应商的 API key 和回调 URL。
- 已参考文本转语音 (TTS) 供应商的官方文档获取身份认证信息（token、appid 等）并了解相关参数配置方式。
实现流程
实现与智能体语音互动的流程如下图所示：
加入 RTC 频道
在你的 App 中调用 joinChannel 加入一个 RTC 频道。
创建对话式智能体
调用创建对话式智能体创建一个智能体实例，并传入上一步中使用的频道名和 Token 让智能体加入同一个 RTC 频道。
提示
- 声网推荐你前往控制台的 Playground 快速体验与 AI 智能体对话，正确配置各项参数并完成体验后，点击右上角的 View code 复制自动生成的服务端 API 调用示例代码。
- 你可以使用第三方在线工具快速得到
Authorization值。将客户 ID 和客户密钥分别填入Username和Password框，得到形如Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=的结果。将该结果替代下面代码中的Authorization: <credentials>即可。
请求
Shell
curl --request post \
--url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/<your_app_id>/join \
--header 'Authorization: Basic <credentials>' \
--data '
{
"name": "unique_name",
"properties": {
"channel": "channel_name",
"token": "token",
"agent_rtc_uid": "0",
"remote_rtc_uids": [
"*"
],
"asr": {
"language": "zh-CN"
},
"llm": {
"url": "https://api.xxxx/v1/xxxx",
"api_key": "xxx",
"system_messages": [
{
"role": "system",
"content": "You are a helpful chatbot."
}
],
"greeting_message": "您好，有什么可以帮您？",
"failure_message": "抱歉，我无法回答这个问题。",
"max_history": 10,
"params": {
"model": "xxxx",
}
},
"tts": {
"vendor": "vendor_name",
"params": {
"key": "xxxx",
"voice_id": "xxxx",
}
}
}
}
'
响应
调用成功后，你会收到如下响应：
JSON
/// 200 OK
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"create_ts": 1737111452,
"status": "RUNNING"
}
同时，智能体会加入到 RTC 频道中，向用户问好；用户则可以开始与智能体对话。
停止对话式智能体
当用户与智能体对话结束后，你可以调用停止对话式智能体，传入创建智能体时返回的 agent_id 让指定智能体离开 RTC 频道。
请求
Shell
curl --request post \
--url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/<your_app_id>/agents/<agentid>/leave \
--header 'Authorization: Basic <credentials>'
响应
调用成功后，你会收到如下响应：
JSON
/// 200 OK
{}
参考信息
开发注意事项
- 目前仅支持使用中文和英文与 AI 智能体互动，其他语种需求联系技术支持反馈。
- 目前单一 App ID 调用服务端 API 的并发用户数 (Peak Concurrent Users) 限制为 20， 如需提升配额，请联系技术支持申请。