# 使用 Go SDK 实现对话式 AI 引擎 (/zh-CN/ai/get-started/quick-start-go)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
本文向新手介绍如何使用声网 Go SDK 实现对话式 AI 引擎。
Go SDK 旨在帮助开发者更轻松集成声网 RESTful API。该 SDK 具有如下特性:
- 简化通信流程:通过封装 RESTful API 的请求和响应处理,让你与 RESTful API 的通信更加简单。
- 保障可用性:遇到 DNS 解析失败、网络错误、请求超时等网络问题时,会自动切换到最佳域名,确保 REST 服务的可用性。
- API 易用性:提供简洁易懂的 API,让你能轻松实现创建对话式智能体、停止对话式智能体等常用功能。
- 其他优势:基于 Go 语言编写,具有高效性、并发性、可扩展性。
## 前提条件 [#前提条件]
开始前请确保:
- 已集成 [Go](https://go.dev/dl/) 1.18 或以上版本。
- 已参考[开通服务](/zh-CN/ai/get-started/enable-service)在声网控制台完成以下步骤:
- 为你的项目开通声网对话式 AI 引擎。
- 获取 App ID:声网随机生成的字符串,用于识别你的项目和调用对话式智能体 RESTful API。
- 获取客户 ID 和客户密钥:用于在调用对话式 AI 引擎 RESTful API 时进行 HTTP 鉴权。
- 生成临时 Token:Token 也称为动态密钥,用于在加入 RTC 频道时对用户鉴权。临时 Token 的有效期为 24 小时。在生产环境中,你需要参考[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)在你的 App 服务端生成 Token。
- 已参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)集成 v4.5.1 及以上版本的实时互动 SDK,并在你的 App 中实现基本的实时音视频功能。
- 已获取大语言模型 (LLM) 供应商的 API key 和回调 URL。
- 已参考文本转语音 (TTS) 供应商的官方文档获取身份认证信息(Token、App ID 等)并了解相关参数配置方式。
## 创建项目并安装 SDK [#创建项目并安装-sdk]
#### 创建项目 [#创建项目]
参考如下步骤创建并配置新项目。
1. 创建一个名为 `test-convoai` 的空项目文件夹。
2. 进入 `test-convoai` 路径,执行如下命令初始化 Go 模块。
```shell
go mod init test-convoai
```
3. 在项目路径下,新建一个空的 `main.go` 文件,我们会在这个文件中实现一个极简的对话式 AI 引擎任务。
#### 安装 SDK [#安装-sdk]
在项目路径下,执行如下命令,安装 Go SDK。
```shell
# 安装 Go SDK
go get -u github.com/AgoraIO-Community/agora-rest-client-go
# 更新依赖
go mod tidy
```
## 实现对话式 AI 引擎 [#实现对话式-ai-引擎]
本节介绍实现对话式 AI 引擎的核心 Go 代码。你可以根据你的需求选择一种方式阅读本节内容:
**快速跑通**:如果只想快速跑通示例代码,不关心实现细节。你可以复制下面的完整示例代码到 `main.go` 文件中,并参考[定义变量](#定义变量)配置相关参数,之后跳到[与智能体对话](#与智能体对话)章节继续跑通。
```go
package main
import (
"context"
"log"
"time"
"github.com/AgoraIO-Community/agora-rest-client-go/agora/auth"
"github.com/AgoraIO-Community/agora-rest-client-go/agora/domain"
agoraLogger "github.com/AgoraIO-Community/agora-rest-client-go/agora/log"
agoraUtils "github.com/AgoraIO-Community/agora-rest-client-go/agora/utils"
"github.com/AgoraIO-Community/agora-rest-client-go/services/convoai"
"github.com/AgoraIO-Community/agora-rest-client-go/services/convoai/req"
)
const (
appId = ""
cname = ""
agentRtcUid = ""
username = ""
password = ""
agentRtcToken = ""
llmURL = ""
llmAPIKey = ""
llmModel = ""
ttsBytedanceToken = ""
ttsBytedanceAppId = ""
ttsBytedanceCluster = ""
ttsBytedanceVoiceType = ""
)
func main() {
log.SetFlags(log.LstdFlags | log.Lshortfile)
// 初始化对话式 AI 引擎 REST Client 配置
config := &convoai.Config{
AppID: appId,
Credential: auth.NewBasicAuthCredential(username, password),
// 指定服务器所在区域,可选 CN、EU、AP、US
// REST Client 会根据配置的区域自动切换使用最佳域名
DomainArea: domain.CN,
// 指定日志输出级别。可选 DebugLevel、InfoLevel、WarningLevel、ErrLevel
// 要禁用日志输出,设置 logger 为 DiscardLogger
Logger: agoraLogger.NewDefaultLogger(agoraLogger.DebugLevel),
// 指定服务区域。可选 ChineseMainlandServiceRegion、GlobalServiceRegion
// ChineseMainlandServiceRegion 和 GlobalServiceRegion 是两个不同的服务
ServiceRegion: convoai.ChineseMainlandServiceRegion,
}
// 初始化对话式 AI 引擎 REST Client
convoaiClient, err := convoai.NewClient(config)
if err != nil {
log.Fatalln(err)
}
ctx := context.Background()
name := appId + ":" + cname
// 创建对话式智能体
joinResp, err := convoaiClient.Join(ctx, name, &req.JoinPropertiesReqBody{
Token: agentRtcToken,
Channel: cname,
AgentRtcUId: agentRtcUid,
RemoteRtcUIds: []string{"*"},
EnableStringUId: agoraUtils.Ptr(false),
IdleTimeout: agoraUtils.Ptr(120),
LLM: &req.JoinPropertiesCustomLLMBody{
Url: llmURL,
APIKey: llmAPIKey,
SystemMessages: []map[string]any{
{
"role": "system",
"content": "You are a helpful chatbot。",
},
},
Params: map[string]any{
"model": llmModel,
"max_tokens": 1024,
},
MaxHistory: agoraUtils.Ptr(30),
GreetingMessage: "Hello,how can I help you?",
},
TTS: &req.JoinPropertiesTTSBody{
Vendor: req.BytedanceTTSVendor,
Params: &req.TTSBytedanceVendorParams{
Token: ttsBytedanceToken,
AppId: ttsBytedanceAppId,
Cluster: ttsBytedanceCluster,
VoiceType: ttsBytedanceVoiceType,
SpeedRatio: 1.0,
VolumeRatio: 1.0,
PitchRatio: 1.0,
Emotion: "happy",
},
},
})
if err != nil {
log.Fatalln(err)
}
if joinResp.IsSuccess() {
log.Printf("Join success:%+v", joinResp)
} else {
log.Printf("Join failed:%+v", joinResp)
return
}
agentId := joinResp.SuccessResp.AgentId
log.Printf("agentId:%s", agentId)
defer func() {
// 停止对话式智能体
leaveResp, err := convoaiClient.Leave(ctx, agentId)
if err != nil {
log.Fatalln(err)
}
if leaveResp.IsSuccess() {
log.Printf("Leave success:%+v", leaveResp)
} else {
log.Printf("Leave failed:%+v", leaveResp)
return
}
}()
// 列出对话式智能体
listResp, err := convoaiClient.List(ctx,
req.WithState(2),
req.WithLimit(10),
)
if err != nil {
log.Fatalln(err)
}
if listResp.IsSuccess() {
log.Printf("List success:%+v", listResp)
} else {
log.Printf("List failed:%+v", listResp)
return
}
if listResp.SuccessRes.Data.Count > 0 {
for _, agent := range listResp.SuccessRes.Data.List {
log.Printf("Agent:%+v\n", agent)
}
} else {
log.Printf("No agent found\n")
}
// 保持智能体运行状态 60 秒
time.Sleep(time.Second * 60)
}
```
**了解实现细节**:如果你想了解实现对话式 AI 引擎的各个核心步骤,或需要根据你的需求修改示例代码(例如使用 string 型 UID,或使用其他 TTS 供应商),可以继续阅读本节内容。
### 引入 SDK [#引入-sdk]
在你的 `main.go` 文件中添加如下代码,以引入 Go SDK 中跑通快速开始需要用到的依赖项。
```go
package main
import (
"context"
"log"
"time"
"github.com/AgoraIO-Community/agora-rest-client-go/agora/auth"
"github.com/AgoraIO-Community/agora-rest-client-go/agora/domain"
agoraLogger "github.com/AgoraIO-Community/agora-rest-client-go/agora/log"
agoraUtils "github.com/AgoraIO-Community/agora-rest-client-go/agora/utils"
"github.com/AgoraIO-Community/agora-rest-client-go/services/convoai"
"github.com/AgoraIO-Community/agora-rest-client-go/services/convoai/req"
)
```
### 定义变量 [#定义变量]
在 `main.go` 文件中,添加如下代码,定义或配置创建一个对话式智能体所需的关键参数。
```go
const (
// 声网参数配置
appId = ""
cname = ""
agentRtcUid = ""
username = ""
password = ""
agentRtcToken = ""
// LLM 参数配置
llmURL = ""
llmAPIKey = ""
llmModel = ""
// TTS 参数配置(以火山 TTS 为例)
ttsBytedanceToken = ""
ttsBytedanceAppId = ""
ttsBytedanceCluster = ""
ttsBytedanceVoiceType = ""
)
```
其中,需要配置的参数可以分为三类:
- 声网参数配置:
- `appId`:你的声网 App ID。
- `cname`:对话式智能体加入的 RTC 频道名。你需要填入创建临时 Token 时使用的频道名。
- `agentRtcUid`:对话式智能体在 RTC 频道内的用户 ID。默认使用 Int 型 UID,例如 `123`,如需使用 String 型 UID,例如 `"123"`,请将后续步骤代码中的 `EnableStringUId` 设置为 `true`。
- `username` 和 `password`:你的声网客户 ID 和客户密钥。
- `agentRtcToken`:对话式智能体加入 RTC 频道使用的 Token。填入临时 Token 即可。
- LLM 参数配置:
- `llmURL`:LLM API 回调地址。
- `llmAPIKey`:LLM API Key。
- `llmModel`:大语言模型名。
- TTS 参数配置:示例代码中以火山 TTS 为例,你可以根据实际情况选择其他 TTS 供应商,并参考 [`JoinPropertiesTTSBody`](/zh-CN/api-reference/conversational-ai/restclient-go/struct#joinpropertiesttsbody) 了解具体配置方式。
### 创建并初始化 Client [#创建并初始化-client]
在 `main` 函数中初始化声网配置,调用 [`NewClient`](/zh-CN/api-reference/conversational-ai/restclient-go/client.go#newclient) 创建对话式 AI 引擎 REST Client,并设置日志输出格式:
```go
func main() {
log.SetFlags(log.LstdFlags | log.Lshortfile)
// 初始化对话式 AI 引擎 REST Client 配置
config := &convoai.Config{
AppID: appId,
Credential: auth.NewBasicAuthCredential(username, password),
// 指定服务器所在区域,可选 CN、EU、AP、US
// REST Client 会根据配置的区域自动切换使用最佳域名
DomainArea: domain.CN,
// 指定日志输出级别
// 要禁用日志输出
Logger: agoraLogger.NewDefaultLogger(agoraLogger.DebugLevel),
// 指定服务区域,可选 ChineseMainlandServiceRegion、GlobalServiceRegion
// ChineseMainlandServiceRegion 和 GlobalServiceRegion 是两个不同的服务
ServiceRegion: convoai.ChineseMainlandServiceRegion,
}
// 初始化对话式 AI 引擎 REST Client
convoaiClient, err := convoai.NewClient(config)
if err != nil {
log.Fatalln(err)
}
ctx := context.Background()
// ... 后续代码
}
```
### 创建对话式智能体 [#创建对话式智能体]
使用 [`Join`](/zh-CN/api-reference/conversational-ai/restclient-go/client.go#join) 方法创建对话式智能体,并传入 LLM 和 TTS 的配置参数([`JoinPropertiesCustomLLMBody`](/zh-CN/api-reference/conversational-ai/restclient-go/struct#joinpropertiescustomllmbody) 和 [`JoinPropertiesTTSBody`](/zh-CN/api-reference/conversational-ai/restclient-go/struct#joinpropertiesttsbody)):
```go
// ... 前面的配置代码
// 为智能体设置名称,通常使用 appId:频道名 的格式
name := appId + ":" + cname
// 创建对话式智能体
joinResp, err := convoaiClient.Join(ctx, name, &req.JoinPropertiesReqBody{
Token: agentRtcToken,
Channel: cname,
AgentRtcUId: agentRtcUid,
RemoteRtcUIds: []string{"*"},
EnableStringUId: agoraUtils.Ptr(false),
IdleTimeout: agoraUtils.Ptr(120),
LLM: &req.JoinPropertiesCustomLLMBody{
Url: llmURL,
APIKey: llmAPIKey,
SystemMessages: []map[string]any{
{
"role": "system",
"content": "You are a helpful chatbot。",
},
},
Params: map[string]any{
"model": llmModel,
"max_tokens": 1024,
},
MaxHistory: agoraUtils.Ptr(30),
GreetingMessage: "Hello,how can I help you?",
},
TTS: &req.JoinPropertiesTTSBody{
Vendor: req.BytedanceTTSVendor,
Params: &req.TTSBytedanceVendorParams{
Token: ttsBytedanceToken,
AppId: ttsBytedanceAppId,
Cluster: ttsBytedanceCluster,
VoiceType: ttsBytedanceVoiceType,
SpeedRatio: 1.0,
VolumeRatio: 1.0,
PitchRatio: 1.0,
Emotion: "happy",
},
},
})
if err != nil {
log.Fatalln(err)
}
if joinResp.IsSuccess() {
log.Printf("Join success:%+v", joinResp)
} else {
log.Printf("Join failed:%+v", joinResp)
return
}
// 获取对话式智能体 ID,用于后续操作
agentId := joinResp.SuccessResp.AgentId
log.Printf("agentId:%s", agentId)
```
### 停止对话式智能体 [#停止对话式智能体]
为了确保程序结束时能够正确停止对话式智能体,添加延迟执行的 `Leave` 操作:
```go
// ... 前面的代码
// 设置延迟执行,确保程序结束时停止对话式智能体
defer func() {
// 停止对话式智能体
leaveResp, err := convoaiClient.Leave(ctx, agentId)
if err != nil {
log.Fatalln(err)
}
if leaveResp.IsSuccess() {
log.Printf("Leave success:%+v", leaveResp)
} else {
log.Printf("Leave failed:%+v", leaveResp)
return
}
}()
// ... 后续代码
```
### 列出当前对话式智能体 [#列出当前对话式智能体]
使用 [`List`](/zh-CN/api-reference/conversational-ai/restclient-go/client.go#list) 方法获取当前运行的对话式智能体列表:
```go
// ... 前面的代码
// 列出对话式智能体
listResp, err := convoaiClient.List(ctx,
req.WithState(2),
req.WithLimit(10),
)
if err != nil {
log.Fatalln(err)
}
if listResp.IsSuccess() {
log.Printf("List success:%+v", listResp)
} else {
log.Printf("List failed:%+v", listResp)
return
}
if listResp.SuccessRes.Data.Count > 0 {
for _, agent := range listResp.SuccessRes.Data.List {
log.Printf("Agent:%+v\n", agent)
}
} else {
log.Printf("No agent found\n")
}
// 保持智能体运行状态 60 秒
time.Sleep(time.Second * 60)
```
## 与智能体对话 [#与智能体对话]
本节介绍如何让智能体和用户加入同一个 RTC 频道,并实现对话互动。
### 用户加入频道 [#用户加入频道]
在你的 App 中使用和智能体不同的用户 ID 和相同的 Token 和频道名加入 RTC 频道。
:::info[信息]
你也可以使用[实时互动 Web Demo](https://webdemo.agora.io/index.html) 加入 RTC 频道。完成**初始化设置**后,在左侧菜单选择**快速开始-音视频通话**,填入和智能体不同的用户 ID 和相同的 Token 和频道名加入 RTC 频道。
:::
### 智能体加入频道 [#智能体加入频道]
在项目路径下,执行如下命令,启动智能体。
```shell
go run main.go
```
运行成功后,你会看到如下日志:
```shell
DEBUG agora-rest-client-go 2025/03/20 07:20:34 client.go:148: http response:{"agent_id":"1NT29X0XEAxxxxxxPHSDRNZYF","create_ts":1742455234,"status":"RUNNING"}
2025/03/20 15:20:34 main.go:103: Join success:&{Response:{BaseResponse:0xc0002169c0 ErrResponse:{Detail: Reason:}} SuccessResp:{AgentId:1NT29X0XEAxxxxxxPHSDRNZYF CreateTs:1742455234 Status:RUNNING}}
2025/03/20 15:20:34 main.go:111: agentId:1NT29X0XEAxxxxxxPHSDRNZYF
```
之后,智能体会加入 RTC 频道,并向用户发送问候语。
:::warning[注意]
智能体加入频道后,如果频道内没有其他用户,一段时间后(示例代码中设置为 120 秒)智能体会自动离开频道。
:::
### 用户与智能体对话 [#用户与智能体对话]
双方加入频道后,用户可以直接和智能体对话,智能体会使用语音回答。
## 参考信息 [#参考信息]
### 示例项目 [#示例项目]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
agora-rest-client-go} href="https://gitee.com/agoraio-community/agora-rest-client-go/tree/main/examples/convoai" />
agora-rest-client-go} href="https://github.com/AgoraIO-Community/agora-rest-client-go/tree/main/examples/convoai" />
### API 参考 [#api-参考]
- 对话式 AI 引擎 Go SDK API 参考