# 使用 RESTful API 实现对话式 AI 引擎 (/zh-CN/ai/get-started/quick-start)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

本文介绍如何调用声网对话式 AI 引擎 RESTful API 创建一个对话式智能体 (Conversation AI Agent)，并实现与 AI 智能体对话互动。

## 前提条件 [#前提条件]

开始前，请确保：

- 已参考[开通服务](/zh-CN/ai/get-started/enable-service)在声网控制台完成以下步骤：
    - 为你的项目开通声网对话式 AI 引擎。
    - 获取 App ID：声网随机生成的字符串，用于识别你的项目和调用对话式智能体 RESTful API。
    - 获取客户 ID 和客户密钥：使用 HTTP 基本认证调用对话式 AI 引擎 RESTful API 时需要。
    - 生成 Token：使用 [Token 认证](/zh-CN/ai/build/http-basic-auth#使用-token-认证)调用 RESTful API 时需要。Token 必须以 `007` 开头，并包含 ConvoAI service。在生产环境中，你需要在你的 App 服务端生成 Token。
    - 生成 RTC Token：用于智能体和用户加入 RTC 频道。该 Token 与 REST 鉴权 Token 的用途不同。
- 已参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)集成 v4.5.1 及以上版本的实时互动 SDK，并在你的 App 中实现基本的实时音视频功能。
  :::info[信息]
  如果你想使用嵌入式智能硬件与 AI 智能体对话，你可以集成 1.9.x 及以上版本的 RTSA C SDK，并参考实现媒体流和信令传输在你的设备端实现基本的实时音视频功能。
  :::
- 已获取大语言模型 (LLM) 供应商的 API key 和回调 URL。
- 已参考文本转语音 (TTS) 供应商的官方文档获取身份认证信息（Token、App ID 等）并了解相关参数配置方式。

## 实现流程 [#实现流程]

实现与智能体语音互动的流程如下图所示：

<DocsImage alt="与智能体语音互动的实现流程" src="https://web-cdn.agora.io/docs-portal/img/convoai/quick-start.svg" displayWidth="75%" />

### 加入 RTC 频道 [#加入-rtc-频道]

在你的 App 中调用 `joinChannel` 加入一个 RTC 频道。

### 创建对话式智能体 [#创建对话式智能体]

调用[创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)创建一个智能体实例，并传入上一步中使用的频道名和 Token 让智能体加入同一个 RTC 频道。

:::info[提示]
- 声网推荐你前往控制台的 [**Playground**](https://console.shengwang.cn/product/ConversationAI?tab=Playground) 快速体验与 AI 智能体对话，正确配置各项参数并完成体验后，点击右上角的 **View code** 复制自动生成的服务端 API 调用示例代码。
- 你可以使用两种鉴权方式：
  - 使用 Token 认证时，将以 `007` 开头且包含 ConvoAI service 的 Token 填入 HTTP 请求头的 `Authorization` 字段。例如：`Authorization: agora token="007abcxxxxxxx123"`。
  - 使用 HTTP 基本认证时，你可以使用[第三方在线工具](https://www.debugbear.com/basic-auth-header-generator)快速得到 `Authorization` 值。将客户 ID 和客户密钥分别填入 `Username` 和 `Password` 框，得到形如 `Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=` 的结果。将该结果替代下面代码中的 `Authorization: agora token="007abcxxxxxxx123"` 即可。
  - Header 中的 Token 用于 REST 鉴权，Request Body 中 `properties.token` 使用的 Token 用于智能体加入 RTC 频道，不参与 REST 鉴权。
:::

#### 请求 [#请求]

```bash
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
        }
      }
    }
  }
}
'
```

#### 响应 [#响应]

调用成功后，你会收到如下响应：

```json
/// 200 OK
{
  // [!code highlight:1]
  "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
  "create_ts": 1737111452,
  "status": "RUNNING"
}
```

同时，智能体会加入到 RTC 频道中，向用户问好；用户则可以开始与智能体对话。

### 停止对话式智能体 [#停止对话式智能体]

当用户与智能体对话结束后，你可以调用[停止对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/leave)，传入创建智能体时返回的 `agent_id` 让指定智能体离开 RTC 频道。

#### 请求 [#请求-1]

```bash
curl --request POST \
# [!code highlight:2]
  --url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/<your_app_id>/agents/<agentid>/leave \
  --header 'Authorization: agora token="007abcxxxxxxx123"' \
```

#### 响应 [#响应-1]

调用成功后，你会收到如下响应：

```json
/// 200 OK
{}
```

## 参考信息 [#参考信息]

### 开发注意事项 [#开发注意事项]

- 目前仅支持使用中文和英文与 AI 智能体互动，其他语种需求[联系技术支持](https://ticket.shengwang.cn)反馈。
- 目前单一 App ID 调用服务端 API 的并发用户数 (Peak Concurrent Users) 限制为 20， 如需提升配额，请[联系技术支持](https://ticket.shengwang.cn)申请。

### API 参考 [#api-参考]

- [创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)
- [停止对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/leave)
- [更新智能体配置](/zh-CN/api-reference/api-ref/conversational-ai/update)
- [查询智能体状态](/zh-CN/api-reference/api-ref/conversational-ai/query)
- [获取智能体列表](/zh-CN/api-reference/api-ref/conversational-ai/list)
- [响应状态码](/zh-CN/api-reference/conversational-ai/rest-api/api/response-code)