一、为什么我想搭一个语音 Agent

ChatGPT 4o 刚出语音模式的时候，我第一时间就试了。那种对话体验确实比之前任何语音助手都自然——没有明显的"等待-识别-回复"的机械感。当时我就想，能不能自己搭一个？

于是开始拼积木：Deepgram 做 ASR、OpenAI 做 LLM、MiniMax 做 TTS，再加上 WebSocket 传输。demo 跑通了，但问题也来了：延迟经常 2 秒以上、打断逻辑写了一堆 if-else 还是经常出错、WebSocket 在不稳定网络下频繁断连。

这时候我知道了 Agora 和 OpenAI 的合作——2024 年 10 月，Agora 被官宣为 OpenAI Realtime API 的官方合作伙伴。之前 OpenAI 自己用的是 WebSocket + 插网线的方案，就在传输层面不太能保证。翻了翻 Agora 的 Conversational AI 文档，发现它把语音 Agent 要的四层——实时传输、Agent 运行时、AI 模型、端上体验——打包成了一个引擎。不需要自己拼 ASR+LLM+TTS+打断逻辑+传输。

正好周末有空，我决定用它的 Quickstart 完整跑一遍，看看到底几斤几两。这篇文章就是全过程记录——从零到能对话，好的坏的都写上。

二、动手：从零到第一次对话

2.1 准备工作

• Python 3.10+ — Windows 用户确认 python --version 能正常输出

• Git — agora init 需要 git 来克隆模板仓库，下载 Git for Windows，安装时选 “Git from the command line”

• Bun（JavaScript 运行时）— 一会儿装

• Agora CLI — 一会儿装

• 一个浏览器（Chrome / Edge）

• 一个 Agora 账号 — 下一步注册

2.2 注册 Agora 并获取凭据

打开 Agora Console，用邮箱注册（或用 GitHub / Google 登录）。注册后进入控制台。

会看到在Your project：

• App ID — 一串数字

• App Certificate — 需要点 “show” 才能看到（**注意：**Console 默认不显示）

这一步非常关键：下载凭据文件！在项目页面点击右上角的 Download 按钮，选择下载 env 文件（会得到一个 env.download）。后面要把这个文件的内容写入项目的 server/.env.local。如果跳过这一步，后端启动后会因为缺少凭据而连不上 Agora 服务，导致只有前端 3000 端口起来，8000 后端实际没有正常工作。

2.3 开通 Conversational AI 引擎

在项目页面左侧菜单找到 Conversational AI，点进去，点击启用 / Enable。

开通后你会获得 300 分钟免费额度。不需要绑定信用卡，不需要自己申请 OpenAI / Deepgram 的 API Key——Agora 的 Managed Mode 默认帮你出了。

2.4 安装开发环境

安装 Bun

Bun 是一个 JavaScript 运行时，Agora 的前端界面（Next.js）需要它。打开 PowerShell（管理员模式），运行：

powershell -c "irm bun.sh/install.ps1 | iex"

安装 Agora CLI

Agora CLI 是官方命令行工具，帮你创建项目、管理凭证、诊断问题。

官方推荐的方式：

irm https://dl.agora.io/cli/install.ps1 | iex

建议大家使用 Windows WSL子系统避免出现和我一样的问题：

如果你的 PowerShell 版本较旧（如 Windows 10 自带的 PowerShell 5.1），上面的命令会报 PropertyNotFoundException: OSArchitecture 错误。

**解决方法：**跳过安装脚本，直接从 GitHub Releases 下载 agora-cli_vX.X.X_windows_amd64.zip（以 v0.2.8 为例：https://github.com/AgoraIO/cli/releases/download/v0.2.8/agora-cli_v0.2.8_windows_amd64.zip）。

下载后解压到桌面，得到 agora.exe。使用时需要带完整路径：C:\Users\Administrator\Desktop\agora.exe。

由于我的电脑装不上，于是我去 Github下载了windows_amd64.zip

将zip文件解压到桌面上

进入cmd验证安装：

cd C:\Users\Administrator\Desktop
.\agora.exe --version

登录 Agora CLI

agora login

这会打开浏览器，让你用刚才注册的 Agora 账号登录。

2.5 创建项目

这是全文最核心的一步，但实际只有一条命令：

agora init my-python --template python

my-python 你可以改成自己喜欢的名字。这条命令会：

1. 自动关联你 Agora 账号下的项目

2. 拉取 Python Quickstart 模板代码（所以需要 Git！）

3. 生成 server/.env.local 文件

Windows 用户必看：修复 package.json

agora init 生成的 package.json 中的脚本使用了很多 Unix 专属命令（bash、test、python3、source venv/bin/activate 等），在 Windows 上会全部报错。直接 bun run setup 或 bun run dev 会只启动前端 3000 端口，后端 8000 起不来。

打开 package.json，找到 scripts 部分，把以下脚本替换成 Windows 兼容版本：

1. setup:env — 改成：

"setup:env": "echo .env.local ok",

2. setup:backend — 改成（注意用你的 Python 实际路径）：

"setup:backend": "cd server && C:/Users/Administrator/AppData/Local/Programs/Python/Python311/python.exe -m venv venv && venv/Scripts/python -m pip install --upgrade pip && venv/Scripts/python -m pip install -r requirements.txt",

如果 python 在你的 PATH 里，可以简化为：

"setup:backend": "cd server && python -m venv venv && venv/Scripts/python -m pip install --upgrade pip && venv/Scripts/python -m pip install -r requirements.txt",

3. dev:backend — 改成：

"dev:backend": "cd server && venv/Scripts/python src/server.py",

4. setup:deps — 改成：

"setup:deps": "echo deps ok",

5. setup:done — 去掉 echo.（CMD 语法，bun 不认识），改成普通 echo。

**关键：**路径中必须用正斜杠 / 而不是反斜杠 \——因为 \S 在 bun 脚本里会被当作转义字符吃掉，导致 bun: command not found: venvScriptspython。

2.6 写入凭据并安装依赖

把 2.2 节下载的 env.download 内容复制到 server/.env.local 中（替换掉原来的占位符）。

如果你已经用 agora init 绑定了账号，也可以运行：

agora project env write server/.env.local

然后安装依赖：

cd my-python
bun install

bun run setup

bun run setup 内部会依次执行：写入 .env.local → 创建 Python venv 并安装后端依赖 → bun install 安装前端依赖。前提是你的 package.json 已经按 2.5 节修复过。

2.7 启动项目

终于到了启动的时刻：

bun run dev

这条命令会同时启动两个服务：

服务	地址	说明
前端界面	http://localhost:3000	浏览器对话 UI（Next.js）
后端 API	http://localhost:8000	FastAPI，签发 Token、启停 Agent

**如何判断启动成功：**终端里应该同时看到 [backend] 和 [frontend] 两个日志流。如果只看到 [frontend] 而 [backend] 报错退出，说明后端没起来——最常见的原因就是 package.json 没修复。

浏览器访问 http://localhost:3000，点击 Start conversation 按钮。

2.8 项目结构关键文件

趁项目在跑，扫一眼目录。几个核心文件：

• server/src/agent.py — 整个 Agent 的配置核心。Prompt、VAD 参数、STT/LLM/TTS 选择都在这里

• server/src/server.py — FastAPI 路由，暴露三个接口：/api/get_config（获取 RTC Token）、/api/startAgent（启停 Agent）、/api/stopAgent

• web/src/components/ConversationComponent.tsx — 前端 RTC 音频采集/播放 + 实时字幕渲染

• web/src/components/LandingPage.tsx — 页面入口，协调 token 获取、agent 启动、RTM 登录、会话结束的完整流程

agent.py 里最关键的配置长这样（默认值）：

ADA_PROMPT = "You are a helpful voice assistant..."
AGENT_GREETING = "Hello, how can I help you today?"

# 轮次检测配置
turn_detection = {
    "type": "semantic_vad",  # 语义 VAD，而不是纯声学 VAD
    "threshold": 0.7,
}

# 默认模型选择（Managed Mode）
stt = DeepgramSTT()
llm = OpenAI(model="gpt-4o-mini")
tts = MiniMaxTTS(voice_id="female-voice-1")

注意这里的 turn_detection 类型是 semantic_vad——它不光检测有没有声音，还会理解语义，判断你是不是说完了。这个比纯声学 VAD（单纯靠音量阈值判断）要聪明得多。

2.9 第一次对话体验

连接上之后，我测试了几轮对话。以下是一段真实记录的对话过程：

**我：**Hello, what’s the weather like in Beijing today?

**Agent：**I don’t have real-time weather data access right now, but I’d suggest checking a weather app or website for the most accurate forecast. Is there anything else I can help with?

页面底部会显示 Pipeline 信息：Deepgram STT → OpenAI LLM (ttfs 711ms) → MiniMax TTS (ttfb 367ms)。两个延迟都在毫秒级，响应相当快。

然后我做了两个关键测试：

1. **打断测试：**Agent 在说话时我插了一句"Wait, stop"，它确实停了。不是那种生硬的截断，而是比较自然地停顿下来听我说话。

2. **停顿测试：**我故意在句子中间停了 2 秒，Agent 没有抢话。这个语义 VAD 确实比纯声学方案靠谱——它知道我只是在组织语言，不是说完了。

实时字幕也很流畅，Transcript 基本和说话同步，没有明显延迟。这对调试非常有用——你能看到 Agent 到底听懂了你说的什么。

**一个最反直觉的地方：你不需要自己去申请 OpenAI key、Deepgram key 或任何 TTS 服务商的 key。**Agora 的 Managed Mode 帮你管了这些——注册账号就有 300 分钟免费额度，开箱即对话。这也是这次体验里让我最意外的一点：本来以为要先去各个平台注册领 Key，结果什么都不用。

如果 Agent 不响应，可以运行诊断：

agora project doctor

它会检查凭证是否有效、网络是否可达、环境变量是否正确绑定。

默认的 Deepgram + OpenAI + MiniMax 组合开箱就能用，但开发者迟早会想换模型。Agora 的这个设计叫 BYOK（Bring Your Own Key）——你可以用自己的 API Key 切换到任何兼容的 ASR/LLM/TTS 提供商。

打开 server/src/agent.py，找到模型配置部分：

# Default managed path: DeepgramSTT + OpenAI + MiniMaxTTS.
llm = OpenAI(
    model="gpt-4o-mini",
    greeting_message=self.greeting,
    failure_message="Please wait a moment.",
    max_history=15,
    max_tokens=1024,
    temperature=0.7,
    top_p=0.95,
)
stt = DeepgramSTT(model="nova-3", language="en")
tts = MiniMaxTTS(model="speech_2_6_turbo", voice_id="English_captivating_female1")

BYOK 的设计思路很清晰：**Provider 层是一个抽象接口，你传什么 Key 就用什么服务。**官方提供了几个内置 Provider（Deepgram、OpenAI、MiniMax、ElevenLabs、Cartesia 等），也支持自己实现兼容接口的 Provider。

以换 TTS 为例，取消注释 agent.py 里对应的代码，填上你的 Key：

# 把上面 tts = MiniMaxTTS(...) 注释掉，换成下面这段

from agora_agent.agentkit.vendors import ElevenLabsTTS
tts = ElevenLabsTTS(
    key=os.getenv("ELEVENLABS_API_KEY"),
    model_id="eleven_flash_v2_5",
    voice_id=os.getenv("ELEVENLABS_VOICE_ID", "pNInz6obpgDQGcFmaJgB"),
)

然后把 ELEVENLABS_API_KEY 加到 server/.env 里。重启 bun run dev，对话的语音就变了。

上述代码仅为示意 BYOK 的思路。具体的 import 路径和参数名以官方 recipe 代码仓库中的实际文件为准。同样方式可以换 STT（Deepgram → 自己的 Key）和 LLM（gpt-4o-mini → 自己的 OpenAI Key 或其他模型）。

说实话，这个设计比我想象的干净。不需要改传输层、不需要动运行时、不需要重新配置打断逻辑——换模型就是换模型，其他层不动。

不过有一点需要注意：**用 BYOK 时，API Key 存在你的服务端（.env 文件里），不会发到 Agora 的服务器。**这意味着计费和配额都是你自己管理，Agora 只负责传输和运行时的部分。

3.1 改问候语

改 server/.env 里的一行：

AGENT_GREETING=你好！我是你自己搭的语音助手，有什么可以帮你的？

重启后，AI 第一句话就会用你写的那句中文问候。

三、说点实话：跑完的真实评价

整体体验下来的真实看法：

做得不错的地方：

1. **Quickstart 确实快，没骗人。**从零到能对话，算上注册账号的时间也不到 15 分钟。而且前后端分离的架构合理——FastAPI + Next.js，改后端配置和改前端 UI 互不影响

2. **延迟很低，通话很自然。**从 Pipeline 信息可以看到：LLM 首字延迟 711ms，TTS 首音延迟 367ms，端到端体感不到 1 秒。比我之前拼积木的方案快了一倍不止

3. **打断和轮次检测开箱即用。**语义 VAD 比我手写的那堆 if-else 靠谱得多。这层如果纯自己写，光调参数就能调一个星期

4. **BYOK 设计干净。**换模型就是换模型，不动其他层。Provider 抽象接口设计合理，没有厂商锁定感

待改进的地方：

1. **Managed Mode 的默认模型组合不是最优。**Deepgram 的英文 ASR 不错，但中文识别偶尔翻车；MiniMax TTS 中文还行、英文节奏感一般。如果能提供几套"推荐组合"（比如中文最佳组合 vs 英文最佳组合）会更友好

2. **Console 对新用户不够友好。**App Certificate 需要手动启用、Conversational AI 功能也藏在菜单里——这些步骤加个新手引导会好很多

3. 建议大家用 Windows 的 WSL环境

如果你想快速验证语音 Agent 的概念、不想自己搞 WebRTC 传输层、或者需要一个开箱就全球低延迟的方案——Agora Conversational AI 是目前跑通概念最快的选择之一。