摘要

这篇文章记录我用 Agora Conversational AI 的 vision recipe 搭一个「会看」的多模态语音助手的过程——对着摄像头说话，它能实时描述画面里有什么。我用 Claude Code + Agora 官方的 Skills/MCP 把它跑了起来，拆了拆多模态到底是怎么接入的，并对比了「级联」和「端到端 Realtime」两条技术路线。
全程零 key、开箱即用，多模态的接入比我预想的省心。

---

一、效果展示

打开网页、允许摄像头、点 Start Conversation

进入页面，提问：它看到了什么

它停顿不到一秒，用语音把眼前的东西描述了出来。我又换了个场景接着试：

体验效果非常不错，延迟低，解析语音准确率高，摄像头画面发生变化后实时回复（页面中语音右侧就是摄像头内容，方便测试我用的是OBS虚拟摄像头）

---

二、Agora 介绍

2.1 Agora 与 Conversational AI Engine

• Agora（声网）：实时音视频 RTC 老牌厂商，全球 SD-RTN 网络；OpenAI Realtime API 首批官方合作伙伴。
• Conversational AI Engine：把语音 Agent 的四层（实时传输 / Agent 运行时 / AI 模型 / 端上体验）打包好，开发者不用自己拼 ASR + LLM + TTS + 打断 + 传输。
  一句话定位：用来快速搭语音智能体的实时对话引擎。

2.2 技术栈解析

• RTC / WebRTC：实时传输层，走 UDP、低延迟、能丢包容忍，还能顺带做回声消除和降噪，是「边说边听、随时打断」的底子。
• STT（语音转文字）：本次用 Deepgram，Agora 托管。
• LLM（大模型）：本次用 gpt-4o-mini，多模态、能看图，也是 Agora 托管。
• TTS（文字转语音）：本次用 MiniMax。
• 多模态 + VAD / turn detection：语音和视觉同时输入，再加上判断「你说完没、能不能打断」的轮次检测。
  具体怎么串起来、画面怎么进去，下一章拆。

三、多模态语音 Agent 剖析

3.1 还是那条流水线，只是 LLM 多了「眼睛」

它用的是经典的级联流水线：Deepgram STT（听）→ gpt-4o-mini（想 + 看图）→ MiniMax TTS（说）。在代码里，这三段就是 Agora agentkit 提供的三个 vendor，串起来异常直观——

#server/src/agent.py
from agora_agent.agentkit.vendors import OpenAI, DeepgramSTT, MiniMaxTTS

stt = DeepgramSTT(model="nova-3", language="en")
llm = OpenAI(model="gpt-4o-mini", input_modalities=INPUT_MODALITIES, ...)
tts = MiniMaxTTS(model="speech_2._6_turbo", voice_id="English_captivating_female1")

agora_agent = agora_agent.with_stt(stt).with_llm(llm).with_tts(tts)

最后那行 .with_stt().with_llm().with_tts() 把三段拼成一条流水线——想换厂商，替换对应那个 vendor 就行，这就是级联式「每层可换」的好处。
多模态的关键在 input_modalities=INPUT_MODALITIES，它定义在 vision_config.py：

#server/src/vision_config.py
INPUT_MODALITIES = ["text", "image"]

这告诉 Agora：除了语音转文字喂给模型，还要把摄像头画面作为图片喂进去。配合 system prompt 里那句「describe the most recent image from their camera」，模型就知道该描述摄像头最新一帧。

3.2 摄像头帧是怎么送到 LLM 的

那摄像头画面具体是怎么进到 LLM 肚子里的？前端推流就两行核心代码：

// web/src/components/ConversationComponent.tsx
const { localMicrophoneTrack } = useLocalMicrophoneTrack(isReady);
const { localCameraTrack }   = useLocalCameraTrack(isReady);
usePublish([localMicrophoneTrack, localCameraTrack]);

useLocalCameraTrack 拿摄像头流，usePublish([mic, camera]) 把麦克风和摄像头两路都推进 RTC 频道。剩下不用你管——Agora 云端捕获推上去的摄像头帧，打包成 image_url 转给 gpt-4o-mini。你不用自己写「截图 → 上传 → 拼 prompt」，推一路 RTC track 就完事。
顺带一提，agent.py 里还有一段 turn_detection 配置（VAD 模式，silence_duration_ms: 480）——这就是「你说完没、能不能打断」在代码里的样子，对应前面讲的语义轮次检测。

3.3 依然零 key

看 agent.py 里 OpenAI 那段：

#server/src/agent.py
self.openai_api_key = os.getenv("OPENAI_API_KEY")  # optional — Agora 托管
self.openai_model = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
llm = OpenAI(api_key=self.openai_api_key, model=self.openai_model, ...)

OPENAI_API_KEY 是 optional——gpt-4o-mini 由 Agora 托管，你不填 key、只给 Agora 的 App ID + App Certificate 就能跑，零门槛。

---

四、用 Claude Code + Agora Skills/MCP 搭

这篇我不是手敲配置搭的，是用 Claude Code 配合 Agora 的三件套搭的。三者分工很清楚：

• Agora CLI：管账号和项目——登录、选项目、写凭证、初始化 demo，是主力。
• Agora Skills（Claude Code plugin）：管「怎么搭」——帮助手选对 starter 和 setup 顺序。
• Agora MCP：管「查文档」——实时拉最新官方文档。
  后两个是给 Claude Code 这个 AI 助手加的 buff：它替你查文档、按官方流程走，你只要给方向。

4.1 工具安装

1. Agora CLI（管账号 / 凭证）

curl -fsSL https://dl.agora.io/cli/install.sh | sh
cd C:\Users\你的用户\bin
agora --help        # 验证装好
#Windows PowerShell 备选
irm https://dl.agora.io/cli/install.ps1 | iex

如果想全局执行agora --help，可以添加一下系统环境变量

2. Agora Skills + MCP（在 Claude Code 里装，Skills 会自动带上 MCP）

#需要先执行Claude code启动
/plugin marketplace add AgoraIO/skills
/plugin install agora

3. 验证整体环境

agora doctor

4.2 登录 + 一句 prompt，让助手自己搭

先登录拿凭证（CLI 会弹浏览器授权）：

agora login

弹出一个链接，需要登录一下

然后给 Claude Code 一句（针对 vision recipe）：

Use Agora Skills and Agora MCP to help me set up the Agora Conversational AI vision recipe (recipe-agent-vision, Python): a voice agent that sees my camera and answers “what do you see?”. Check the official docs first, clone the recipe, write Agora credentials via the CLI, and run it locally.
vision 是 use case recipe，不在 agora init 的 quickstart 模板里，所以走 git clone 那条路，而不是 agora init --template。

接下来基本不用你管——助手（用 Skills 引路、MCP 查文档）会 git clone recipe-agent-vision → bun run setup → 用 agora project env write 写好 App ID + Certificate → bun run dev 把它跑起来。

这里我电脑没有接入摄像头，使用的是OBS的虚拟摄像头

4.3 Agora 官方工具实际体验

Skills（工作流引导）：装上后，它在我搭 Agora 项目时确实给了官方推荐的路径——选哪个 starter、setup 按什么顺序。但有个落差：Skills 引导的主要是 agora init 那套 quickstart 模板（python/nextjs/go），而我要搭的 vision 是 use case recipe，不在 init 模板里。所以 Skills 帮我「认对了路」，但具体步骤还是得我自己 git clone + 看 README。
MCP（查文档）：这个是真省事。过程中遇到「vision 该用 agora init 还是 clone」「它到底要不要 OpenAI key」这种问题，不用自己开网页翻文档，让助手用 Agora MCP 直接查，几秒就确认了。这一层比 Skills 更实用。
非常建议 Windows 的用户使用 WSL 子环境，整体开发体验会更友好。

4.4 备选方案：不用 AI 助手，直接 clone recipe

#1. clone 仓库
git clone https://github.com/AgoraIO-Conversational-AI/recipe-agent-vision
cd recipe-agent-vision

#2. 装依赖（web + Python venv）
bun run setup

#3. 登录 + 写凭证
agora login
agora project use            # 选一个 project
agora project env write server/.env.local

#4. 跑起来
bun run dev

打开 http://localhost:3000 → Start Conversation → 允许摄像头。

---

五、两条路线之争：级联 vs 端到端 Realtime

5.1 我用的这个是「级联式」

我用的 vision recipe 走的是「级联式」：STT → 多模态 LLM → TTS 三段拼起来，模型是托管的 gpt-4o-mini。好处很明显——零 key、每一层都能换能调。

5.2 另一条路：端到端 Realtime MLLM

但 Agora 还有另一条路：recipe-agent-realtime-vision，用单个 OpenAI Realtime 多模态模型做端到端 voice-to-voice，连 STT 和 TTS 都省了，也能看摄像头。
听起来更先进，但代价很现实：你得自带一个有 Realtime API 权限的 OpenAI key（不便宜），而且官方在 README 里明确标注了它「尚未实测验证」。

5.3 怎么选

结论很直接：先级联，端到端按需再上。 理由是这两条路线现在的「代价」完全不对等：

• 级联（我用的这条）：零 key、注册就能跑、300 分钟免费额度已经把默认的 STT/LLM/TTS 都包了，recipes 现成。代价是延迟是三段累加，但 Agora 的 RTC 网络把端到端也压到了 650ms 左右，对话体验完全够用。
• 端到端 Realtime：理论上延迟更低（单个模型 voice-to-voice，省了三段拼装），但你得自带一个有 Realtime 权限的 OpenAI key（不便宜），而且官方在 README 里明确写了这条路线「尚未实测验证」。
  所以分场景看：
• 验证想法、写 demo、学习、体验 —— 选级联，零门槛，我就是靠它跑通的。
• 已经有 Realtime key、追求极致低延迟、能接受「未验证」的踩坑风险 —— 再去碰端到端。
  一句话：级联是现在能直接用的「主力」，端到端更像是「未来选项」——等技术验证成熟、你有明确的低延迟刚需再说。对绝大多数开发者，没必要现在就趟端到端那趟浑水。

---

六、需要注意的点

6.1 Windows 上跑 bun run setup，直接报 python3 not found

照 README 跑 setup，卡在 setup:server 这步，报 command not found: python3。
原因：recipe 的 setup 脚本是按 Unix 写的——它调 python3（Windows 上只有 python），还 source venv/bin/activate（Windows 的 venv 目录是 Scripts/ 不是 bin/）。两者在 Windows + Git Bash 下都不兼容。
解决：绕开脚本，手动建 venv + 装依赖：

cd server
python -m venv venv
source venv/Scripts/activate
python -m pip install -r requirements.txt

bun run dev 同理会踩（它的 dev:backend 也写了 venv/bin），得手动分跑 backend 和 frontend：

#backend（一个终端）
cd server && venv/Scripts/python src/server.py

#frontend（另一个终端）
cd web && AGENT_BACKEND_URL=http://localhost:8000 bun run dev

建议Windows系统直接使用 WSL 子环境进行开发，兼容性更好。

6.2 写凭证报 No project selected

跑 agora project env write 时报 No project selected。
原因：账号下有 project，但 CLI 不知道用哪个（没默认绑定）。
解决：先 list 看 project ID，再带上 --project 写：

agora project list
agora project env write server/.env.local --project <project-id>

或先绑定一次：agora project use

6.3 机器没摄像头：DEVICE_NOT_FOUND + OBS 两连坑

页面起来了，Console 报 AgoraRTCError DEVICE_NOT_FOUND。
原因：台式机 / 远程桌面 / 虚拟机 often 没有摄像头硬件。注意这是「设备没找到」，不是「权限被拒」——权限被拒会是 PERMISSION_DENIED。
解决：装 OBS Virtual Camera 当虚拟摄像头，但有两个连环坑：

1. OBS 要以管理员身份运行，再点「启动虚拟摄像机」，驱动才注册（普通权限会被静默拒绝，系统里查不到设备）。
2. 注册后浏览器要完全重启（杀掉残留进程再开），否则设备列表是旧的、识别不到 OBS Virtual Camera。

---

七、评价：看得有多准、适合干嘛

7.1 好的地方

• 零 key 真的开箱即用——不用申请 OpenAI / Deepgram / MiniMax 的 key，注册 Agora 账号、CLI 写个凭证就能跑，门槛低得有点不真实。
• 多模态接入很省心——前端推一路 RTC track（usePublish），后端一句 input_modalities=[“text”,“image”]，剩下 Agora 云帮你把摄像头帧喂给 LLM，不用自己写图像上传那一坨。
• 流水线可换可调——STT / LLM / TTS 是三个独立 vendor，想换厂商换一个就行，这是级联式的好处。
• 为体验做了底层优化——代码里能看到为低延迟选了 chorus profile、为可打断配了 turn_detection（VAD）。

7.2 适合人群

• 适合想快速验证多模态语音 Agent 想法、做 demo、学习 / 测评；尤其 macOS / Linux 环境（少踩一半坑）。
• Agora 的全球网络也是一大特点。公司业务要出海，或者国内和海外用户都需要覆盖，全球网络很占优势；对比之下，OpenAI 的另一个合作伙伴 LiveKit 当时在亚洲没有节点，延迟会高很多， 这些业务场景 ConvoAI 明显更适合。

---

总结

这次用 Claude Code + Agora 三件套（CLI + Skills + MCP），零 key 跑通了一个会「看」的多模态语音 Agent，也把它拆了个底朝天——级联流水线怎么串、摄像头帧怎么进 LLM、级联和端到端两条路线怎么选，心里都有数了。
Agora 这套 Conversational AI Engine 给我的整体体会是：它把「搭语音 Agent」这件本来很碎的事（传输 + 运行时 + 模型 + 打断）打包得确实到位——零 key + 流水线可换，让验证想法的门槛极低，代码里为低延迟（chorus profile + 全球 RTC 网络）和可打断做的优化也是实打实的，对话延迟低、体验跟手。
下一步我想把它和之前做的别的 demo 结合一下 —— 同一条级联流水线，换个 LLM 能力就行，这正是这种架构的乐趣。