# 使用 Agents SDK 实现对话式 AI 引擎 (/zh-CN/ai/get-started/quick-start-agent)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
本文介绍如何使用声网 `Agents SDK` 快速创建一个对话式智能体 (Conversation AI Agent),并实现与 AI 智能体对话互动。
Agents SDK 采用 `AgentKit` 接入方式。相比直接调用 RESTful API,SDK 可以帮助你完成以下工作:
- 使用客户端对象统一管理声网鉴权和区域路由。
- 使用 `Agent` 组装智能体的 STT、LLM 和 TTS 配置。
- 使用 `AgentSession` 启动和停止智能体会话。
- 在 app credentials 模式下自动生成智能体侧所需的 ConvoAI REST 鉴权和 RTC 入会 Token。
## 前提条件 [#前提条件]
开始前,请确保:
- 已参考[开通服务](/zh-CN/ai/get-started/enable-service)在声网控制台完成以下步骤:
- 为你的项目开通声网对话式 AI 引擎。
- 获取 App ID。
- 获取 App Certificate。
- 为用户侧客户端生成 RTC 临时 Token。
- 已参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)集成 v4.5.1 及以上版本的实时互动 SDK,并在你的 App 中实现基本的实时音视频功能。
- 已获取 LLM 供应商的 API key。本文示例使用阿里云百炼兼容 OpenAI 格式的接口,可以参考阿里云百炼[获取 API Key](https://help.aliyun.com/zh/model-studio/get-api-key)。
- 已获取 TTS 供应商凭据。本文示例使用火山引擎 TTS。可以参考[火山引擎官方文档](https://docs.volcengine.com/docs/6561/196768?lang=zh#q1%EF%BC%9A%E5%93%AA%E9%87%8C%E5%8F%AF%E4%BB%A5%E8%8E%B7%E5%8F%96%E5%88%B0%E4%BB%A5%E4%B8%8B%E5%8F%82%E6%95%B0appid%EF%BC%8Ccluster%EF%BC%8Ctoken%EF%BC%8Cauthorization-type%EF%BC%8Csecret-key-%EF%BC%9F)获取 `token`、`app_id`、`cluster`。
:::info[信息]
如果你希望先验证服务端逻辑,也可以使用[实时互动 Web Demo](https://webdemo.agora.io/index.html)作为用户侧客户端加入 RTC 频道,与智能体对话。
:::
## 创建项目 [#创建项目]
Go
Python
TypeScript
创建一个名为 `test-convoai-agent` 的空项目文件夹:
```shell
mkdir test-convoai-agent
cd test-convoai-agent
```
初始化 Go 模块:
```shell
go mod init test-convoai-agent
```
在项目路径下创建以下文件:
```text
test-convoai-agent/
├── .env
├── go.mod
└── main.go
```
创建一个名为 `test-convoai-agent` 的空项目文件夹:
```shell
mkdir test-convoai-agent
cd test-convoai-agent
```
创建并激活 Python 虚拟环境:
```shell
python -m venv .venv
source .venv/bin/activate
```
在项目路径下创建以下文件:
```text
test-convoai-agent/
├── .env
├── main.py
└── requirements.txt
```
创建一个名为 `test-convoai-agent` 的空项目文件夹:
```shell
mkdir test-convoai-agent
cd test-convoai-agent
```
初始化 Node.js 项目:
```shell
npm init -y
```
在项目路径下创建以下文件:
```text
test-convoai-agent/
├── .env
├── package.json
├── src/
│ └── main.ts
└── tsconfig.json
```
## 安装 SDK [#安装-sdk]
Go
Python
TypeScript
安装 Go SDK 和本地 `.env` 读取依赖:
```shell
go get github.com/AgoraIO/agora-agents-go/v2@latest
go get github.com/joho/godotenv@v1.5.1
go mod tidy
```
Go 示例使用 `agentkit/cn` 和 `agentkit/cn/vendors`,该国内版 facade 会自动使用中国大陆区域路由。
在 `requirements.txt` 中添加如下内容:
```text
agora-agents
python-dotenv==1.0.1
```
安装依赖:
```shell
pip install -r requirements.txt
```
安装 TypeScript SDK 和运行依赖:
```shell
npm install agora-agents dotenv@16.4.7
npm install -D typescript@~5.7.2 tsx @types/node
```
在 `package.json` 中添加运行脚本:
```json
{
"type": "module",
"scripts": {
"start": "tsx src/main.ts"
}
}
```
在 `tsconfig.json` 中添加如下内容:
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true
},
"include": ["src/**/*.ts"]
}
```
## 配置环境变量 [#配置环境变量]
在 `.env` 中添加如下配置。三种语言示例使用相同的环境变量:
```env
AGORA_APP_ID=
AGORA_APP_CERTIFICATE=
AGORA_CHANNEL=test-channel
AGORA_AGENT_UID=2000
ALIYUN_API_KEY=
BYTEDANCE_TTS_TOKEN=
BYTEDANCE_TTS_APP_ID=
BYTEDANCE_TTS_CLUSTER=volcano_tts
BYTEDANCE_TTS_VOICE_TYPE=BV700_streaming
SESSION_DURATION_SECONDS=60
```
参数说明如下:
- `AGORA_APP_ID`:你的声网 App ID。
- `AGORA_APP_CERTIFICATE`:你的声网 App Certificate。SDK 会使用 App ID 和 App Certificate 自动生成智能体侧 ConvoAI REST 鉴权和 RTC 入会 Token。
- `AGORA_CHANNEL`:智能体要加入的 RTC 频道名。用户侧客户端需要加入同一个频道。
- `AGORA_AGENT_UID`:智能体在 RTC 频道内使用的 UID。请确保该 UID 与用户侧客户端 UID 不同。
- `ALIYUN_API_KEY`:阿里云百炼 LLM 所需 API key。获取方式参考阿里云百炼[获取 API Key](https://help.aliyun.com/zh/model-studio/get-api-key)。
- `BYTEDANCE_TTS_TOKEN`、`BYTEDANCE_TTS_APP_ID`、`BYTEDANCE_TTS_CLUSTER`、`BYTEDANCE_TTS_VOICE_TYPE`:火山引擎 TTS 所需凭据和音色配置。`token`、`app_id`、`cluster` 和音色的获取方式参考[火山引擎官方文档](https://docs.volcengine.com/docs/6561/196768?lang=zh#q1%EF%BC%9A%E5%93%AA%E9%87%8C%E5%8F%AF%E4%BB%A5%E8%8E%B7%E5%8F%96%E5%88%B0%E4%BB%A5%E4%B8%8B%E5%8F%82%E6%95%B0appid%EF%BC%8Ccluster%EF%BC%8Ctoken%EF%BC%8Cauthorization-type%EF%BC%8Csecret-key-%EF%BC%9F)。
- `SESSION_DURATION_SECONDS`:示例启动后保持会话运行的时间,单位为秒。
:::info[信息]
本文示例使用默认的凤鸣 STT,不需要额外准备 STT 供应商凭据。
:::
## 实现智能体 [#实现智能体]
Go
Python
TypeScript
在 `main.go` 中添加如下代码:
```go
package main
import (
"context"
"fmt"
"log"
"os"
"strconv"
"strings"
"time"
Agora "github.com/AgoraIO/agora-agents-go/v2"
agentkit "github.com/AgoraIO/agora-agents-go/v2/agentkit/cn"
vendors "github.com/AgoraIO/agora-agents-go/v2/agentkit/cn/vendors"
"github.com/joho/godotenv"
)
func requireEnv(name string) string {
value := strings.TrimSpace(os.Getenv(name))
if value == "" {
log.Fatalf("missing required environment variable: %s", name)
}
return value
}
func sessionDuration() time.Duration {
raw := strings.TrimSpace(os.Getenv("SESSION_DURATION_SECONDS"))
if raw == "" {
return 60 * time.Second
}
value, err := strconv.Atoi(raw)
if err != nil || value <= 0 {
log.Fatal("SESSION_DURATION_SECONDS must be a positive integer")
}
return time.Duration(value) * time.Second
}
func main() {
_ = godotenv.Load(".env")
ctx := context.Background()
idleTimeout := 120
maxHistory := 10
channel := requireEnv("AGORA_CHANNEL")
agentUID := requireEnv("AGORA_AGENT_UID")
client := agentkit.NewAgoraClient(agentkit.ClientOptions{
AppID: requireEnv("AGORA_APP_ID"),
AppCertificate: requireEnv("AGORA_APP_CERTIFICATE"),
})
agent := agentkit.NewAgent(
client,
agentkit.WithTurnDetectionConfig(&agentkit.TurnDetectionConfig{
Language: Agora.AsrLanguageZhCn.Ptr(),
}),
).WithStt(
vendors.NewFengmingSTT(),
).WithLlm(
vendors.NewAliyun(vendors.AliyunOptions{
APIKey: requireEnv("ALIYUN_API_KEY"),
Model: "qwen-plus",
BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
SystemMessages: []map[string]interface{}{
{
"role": "system",
"content": "You are a concise and helpful voice assistant.",
},
},
GreetingMessage: "你好!请问有什么可以帮你?",
FailureMessage: "抱歉,请稍等一下。",
MaxHistory: &maxHistory,
}),
).WithTts(
vendors.NewBytedanceTTS(vendors.BytedanceTTSOptions{
Token: requireEnv("BYTEDANCE_TTS_TOKEN"),
AppID: requireEnv("BYTEDANCE_TTS_APP_ID"),
Cluster: requireEnv("BYTEDANCE_TTS_CLUSTER"),
VoiceType: requireEnv("BYTEDANCE_TTS_VOICE_TYPE"),
}),
)
session := agent.CreateSession(agentkit.CreateSessionOptions{
Name: fmt.Sprintf("conversation-%d", time.Now().UnixMilli()),
Channel: channel,
AgentUID: agentUID,
RemoteUIDs: []string{"*"},
IdleTimeout: &idleTimeout,
})
agentSessionID, err := session.Start(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println("Agent started:", agentSessionID)
defer func() {
if err := session.Stop(ctx); err != nil {
log.Printf("failed to stop agent: %v", err)
}
fmt.Println("Agent stopped.")
}()
time.Sleep(sessionDuration())
}
```
在 `main.py` 中添加如下代码:
```python
import os
import time
from dotenv import load_dotenv
from agora_agent import Agent, Agora, Area, AliyunLLM, FengmingSTT
from agora_agent.agentkit.vendors.cn import BytedanceTTS
def main() -> None:
load_dotenv(".env")
channel = os.environ["AGORA_CHANNEL"]
agent_uid = os.environ["AGORA_AGENT_UID"]
client = Agora(
area=Area.CN,
app_id=os.environ["AGORA_APP_ID"],
app_certificate=os.environ["AGORA_APP_CERTIFICATE"],
)
agent = (
Agent(client=client, turn_detection={"language": "zh-CN"})
.with_stt(FengmingSTT())
.with_llm(
AliyunLLM(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
model="qwen-plus",
api_key=os.environ["ALIYUN_API_KEY"],
system_messages=[
{
"role": "system",
"content": "You are a concise and helpful voice assistant.",
}
],
greeting_message="你好!请问有什么可以帮你?",
failure_message="抱歉,请稍等一下。",
max_history=10,
)
)
.with_tts(
BytedanceTTS(
token=os.environ["BYTEDANCE_TTS_TOKEN"],
app_id=os.environ["BYTEDANCE_TTS_APP_ID"],
cluster=os.environ.get("BYTEDANCE_TTS_CLUSTER", "volcano_tts"),
voice_type=os.environ.get("BYTEDANCE_TTS_VOICE_TYPE"),
)
)
)
session = agent.create_session(
name=f"conversation-{int(time.time())}",
channel=channel,
agent_uid=agent_uid,
remote_uids=["*"],
idle_timeout=120,
)
agent_session_id = session.start()
print(f"Agent started: {agent_session_id}")
try:
time.sleep(int(os.environ.get("SESSION_DURATION_SECONDS", "60")))
finally:
session.stop()
if __name__ == "__main__":
main()
```
在 `src/main.ts` 中添加如下代码:
```typescript
import {
Agent,
AgoraClient,
AliyunLLM,
Area,
BytedanceTTS,
FengmingSTT,
} from "agora-agents";
import { config as loadDotenv } from "dotenv";
function requireEnv(name: string): string {
const value = process.env[name]?.trim();
if (!value) {
throw new Error(`missing required environment variable: ${name}`);
}
return value;
}
function sessionDurationSeconds(): number {
const raw = process.env.SESSION_DURATION_SECONDS?.trim();
if (!raw) {
return 60;
}
const value = Number.parseInt(raw, 10);
if (!Number.isInteger(value) || value <= 0) {
throw new Error("SESSION_DURATION_SECONDS must be a positive integer");
}
return value;
}
function sleep(seconds: number): Promise {
return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
}
async function main(): Promise {
loadDotenv({ path: ".env" });
const channel = requireEnv("AGORA_CHANNEL");
const agentUid = requireEnv("AGORA_AGENT_UID");
const client = new AgoraClient({
area: Area.CN,
appId: requireEnv("AGORA_APP_ID"),
appCertificate: requireEnv("AGORA_APP_CERTIFICATE"),
});
const agent = new Agent({
client,
turnDetection: { language: "zh-CN" },
})
.withStt(new FengmingSTT())
.withLlm(
new AliyunLLM({
url: "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
model: "qwen-plus",
apiKey: requireEnv("ALIYUN_API_KEY"),
systemMessages: [
{
role: "system",
content: "You are a concise and helpful voice assistant.",
},
],
greetingMessage: "你好!请问有什么可以帮你?",
failureMessage: "抱歉,请稍等一下。",
maxHistory: 10,
}),
)
.withTts(
new BytedanceTTS({
token: requireEnv("BYTEDANCE_TTS_TOKEN"),
appId: requireEnv("BYTEDANCE_TTS_APP_ID"),
cluster: requireEnv("BYTEDANCE_TTS_CLUSTER"),
voiceType: requireEnv("BYTEDANCE_TTS_VOICE_TYPE"),
}),
);
const session = agent.createSession({
name: `conversation-${Date.now()}`,
channel,
agentUid,
remoteUids: ["*"],
idleTimeout: 120,
});
const agentSessionId = await session.start();
console.log("Agent started:", agentSessionId);
try {
await sleep(sessionDurationSeconds());
} finally {
await session.stop();
console.log("Agent stopped.");
}
}
void main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
```
## 用户加入 RTC 频道 [#用户加入-rtc-频道]
在运行智能体前,用户侧客户端需要加入同一个 RTC 频道。
- 如果你使用自己的 App,请确保:
- App ID 与 `.env` 中的 `AGORA_APP_ID` 一致。
- 频道名与 `.env` 中的 `AGORA_CHANNEL` 一致。
- 用户 UID 与 `.env` 中的 `AGORA_AGENT_UID` 不同。
- 用户侧 RTC Token 与频道名和用户 UID 匹配。
- 如果你使用[实时互动 Web Demo](https://webdemo.agora.io/index.html)进行测试,可以按如下方式填写:
- `App ID`:你的声网 App ID。
- `Channel`:`.env` 中的 `AGORA_CHANNEL`,例如 `test-channel`。
- `UID`:用户侧 UID,例如 `1000`。不要使用智能体 UID `2000`。
- `Token`:为该频道和用户 UID 生成的 RTC Token。
## 启动智能体 [#启动智能体]
在项目路径下执行如下命令:
Go
Python
TypeScript
```shell
go run .
```
```shell
python main.py
```
```shell
npm start
```
运行成功后,终端会输出类似如下日志:
```shell
Agent started: A42AT87YF83TN67JD67AT44JK76PF45C
```
确认用户侧客户端已加入同一频道后,直接在 RTC 客户端发言即可开始对话。
当示例运行时间达到 `SESSION_DURATION_SECONDS`,或你在终端按 `Ctrl+C`,程序会调用 `stop()` 或 `Stop()` 停止智能体会话。
## API 参考 [#api-参考]
Go
Python
TypeScript
- [对话式 AI 引擎 Go SDK API 参考](/zh-CN/api-reference/conversational-ai/agent-go)
- [对话式 AI 引擎 Python SDK API 参考](/zh-CN/api-reference/conversational-ai/agent-python)
- [对话式 AI 引擎 TypeScript SDK API 参考](/zh-CN/api-reference/conversational-ai/agent-typescript)