使用 RESTful API 实现对话式 AI 引擎
更新时间不可用
了解如何快速接入对话式 AI 引擎，完成环境准备、参数配置、示例运行和核心流程验证。
本文介绍如何调用声网对话式 AI 引擎 RESTful API 创建一个对话式智能体 (Conversation AI Agent)，并实现与 AI 智能体对话互动。
前提条件
开始前，请确保：
- 已参考开通服务在声网控制台完成以下步骤：
- 为你的项目开通声网对话式 AI 引擎。
- 获取 App ID：声网随机生成的字符串，用于识别你的项目和调用对话式智能体 RESTful API。
- 获取客户 ID 和客户密钥：使用 HTTP 基本认证调用对话式 AI 引擎 RESTful API 时需要。
- 生成 Token：使用 Token 认证调用 RESTful API 时需要。Token 必须以
007开头，并包含 ConvoAI service。在生产环境中，你需要在你的 App 服务端生成 Token。 - 生成 RTC Token：用于智能体和用户加入 RTC 频道。该 Token 与 REST 鉴权 Token 的用途不同。
- 已参考实现音视频互动集成 v4.5.1 及以上版本的实时互动 SDK，并在你的 App 中实现基本的实时音视频功能。
信息
如果你想使用嵌入式智能硬件与 AI 智能体对话，你可以集成 1.9.x 及以上版本的 RTSA C SDK，并参考实现媒体流和信令传输在你的设备端实现基本的实时音视频功能。
- 已获取大语言模型 (LLM) 供应商的 API key 和回调 URL。
- 已参考文本转语音 (TTS) 供应商的官方文档获取身份认证信息（Token、App ID 等）并了解相关参数配置方式。
实现流程
实现与智能体语音互动的流程如下图所示：
加入 RTC 频道
在你的 App 中调用 joinChannel 加入一个 RTC 频道。
创建对话式智能体
调用创建对话式智能体创建一个智能体实例，并传入上一步中使用的频道名和 Token 让智能体加入同一个 RTC 频道。
提示
- 声网推荐你前往控制台的 Playground 快速体验与 AI 智能体对话，正确配置各项参数并完成体验后，点击右上角的 View code 复制自动生成的服务端 API 调用示例代码。
- 你可以使用两种鉴权方式：
- 使用 Token 认证时，将以
007开头且包含 ConvoAI service 的 Token 填入 HTTP 请求头的Authorization字段。例如：Authorization: agora token="007abcxxxxxxx123"。 - 使用 HTTP 基本认证时，你可以使用第三方在线工具快速得到
Authorization值。将客户 ID 和客户密钥分别填入Username和Password框，得到形如Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=的结果。将该结果替代下面代码中的Authorization: agora token="007abcxxxxxxx123"即可。 - Header 中的 Token 用于 REST 鉴权，Request Body 中
properties.token使用的 Token 用于智能体加入 RTC 频道，不参与 REST 鉴权。
- 使用 Token 认证时，将以
请求
curl --request POST \
--url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/<your_app_id>/join \
--header 'Authorization: agora token="007abcxxxxxxx123"' \
--data '
{
"name": "unique_name",
"properties": {
"channel": "channel_name",
"token": "token",
"agent_rtc_uid": "0",
"remote_rtc_uids": [
"123"
],
"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": "minimax",
"params": {
"key": "your-minimax-key",
"model": "speech-01-turbo",
"voice_setting": {
"voice_id": "female-shaonv",
"speed": 1,
"vol": 1,
"pitch": 0,
"emotion": "happy"
},
"audio_setting": {
"sample_rate": 16000
}
}
}
}
}
'响应
调用成功后，你会收到如下响应：
/// 200 OK
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"create_ts": 1737111452,
"status": "RUNNING"
}同时，智能体会加入到 RTC 频道中，向用户问好；用户则可以开始与智能体对话。
停止对话式智能体
当用户与智能体对话结束后，你可以调用停止对话式智能体，传入创建智能体时返回的 agent_id 让指定智能体离开 RTC 频道。
请求
curl --request POST \
--url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/<your_app_id>/agents/<agentid>/leave \
--header 'Authorization: agora token="007abcxxxxxxx123"' \响应
调用成功后，你会收到如下响应：
/// 200 OK
{}参考信息
开发注意事项
- 目前仅支持使用中文和英文与 AI 智能体互动，其他语种需求联系技术支持反馈。
- 目前单一 App ID 调用服务端 API 的并发用户数 (Peak Concurrent Users) 限制为 20， 如需提升配额，请联系技术支持申请。