一、为什么我想搭一个语音 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 | iex
建议大家使用 Windows WSL子系统避免出现和我一样的问题：
如果你的 PowerShell 版本较旧（如 Windows 10 自带的 PowerShell 5.1），上面的命令会报 PropertyNotFoundException: OSArchitecture 错误。
解决方法：跳过安装脚本，直接从 GitHub Releases 下载 agora-cli_vX.X.X_windows_amd64.zip （以 v0.2.8 为例：`
下载后解压到桌面，得到 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 你可以改成自己喜欢的名字。这条命令会：
- 自动关联你 Agora 账号下的项目
- 拉取 Python Quickstart 模板代码（所以需要 Git！）
- 生成
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
这条命令会同时启动两个服务：
| 服务 | 地址 | 说明 |
|---|---|---|
| 前端界面 | 浏览器对话 UI（Next.js） | |
| 后端 API | FastAPI，签发 Token、启停 Agent |
如何判断启动成功：终端里应该同时看到 [backend] 和 [frontend] 两个日志流。如果只看到 [frontend] 而 [backend] 报错退出，说明后端没起来——最常见的原因就是 package.json 没修复。
在浏览器里点开 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",
"threshold": 0.7,
}
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) 。两个延迟都在毫秒级，响应相当快。
接着我专门做了两项关键测试：
- 打断测试：Agent 在说话时我插了一句"Wait, stop"，它确实停了。不是那种生硬的截断，而是比较自然地停顿下来听我说话。
- 停顿测试：我故意在句子中间停了 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，找到模型配置部分：
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：
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，对话里的声音就换成 ElevenLabs 的了。
上述代码仅为示意 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 开口说的第一句就会变成你写下的那句中文问候。
三、说点实话：跑完的真实评价
把整个流程跑下来之后，说说我真实的感受：
做得不错的地方：
- Quickstart 确实快，没骗人。从零到能对话，算上注册账号的时间也不到 15 分钟。而且前后端分离的架构合理——FastAPI + Next.js，改后端配置和改前端 UI 互不影响
- 延迟很低，通话很自然。从 Pipeline 信息可以看到：LLM 首字延迟 711ms，TTS 首音延迟 367ms，端到端体感不到 1 秒。比我之前拼积木的方案快了一倍不止
- 打断和轮次检测开箱即用。语义 VAD 比我手写的那堆 if-else 靠谱得多。这层如果纯自己写，光调参数就能调一个星期
- BYOK 设计干净。换模型就是换模型，不动其他层。Provider 抽象接口设计合理，没有厂商锁定感
待改进的地方：
- Managed Mode 的默认模型组合不是最优。Deepgram 的英文 ASR 不错，但中文识别偶尔翻车；MiniMax TTS 中文还行、英文节奏感一般。如果能提供几套"推荐组合"（比如中文最佳组合 vs 英文最佳组合）会更友好
- Console 对新用户不够友好。App Certificate 需要手动启用、Conversational AI 功能也藏在菜单里——这些步骤加个新手引导会好很多
- 建议大家用 Windows 的 WSL环境
要是你只想快速验证一下语音 Agent 的想法、不愿自己折腾 WebRTC 传输层，又或者需要一个开箱即享全球低延迟的方案——Agora Conversational AI 算得上是目前最快跑通概念的选项之一。
评论0