摘要这篇文章记录我用 Agora Conversational AI 的 vision recipe 搭一个「会看」的多模态语音助手的过程——对着摄像头说话它能实时描述画面里有什么。我用 Claude Code Agora 官方的 Skills/MCP 把它跑了起来拆了拆多模态到底是怎么接入的并对比了「级联」和「端到端 Realtime」两条技术路线。全程零 key、开箱即用多模态的接入比我预想的省心。一、效果展示打开网页、允许摄像头、点 Start Conversation进入页面提问它看到了什么它停顿不到一秒用语音把眼前的东西描述了出来。我又换了个场景接着试体验效果非常不错延迟低解析语音准确率高摄像头画面发生变化后实时回复页面中语音右侧就是摄像头内容方便测试我用的是OBS虚拟摄像头二、Agora 介绍2.1 Agora 与 Conversational AI EngineAgora声网实时音视频 RTC 老牌厂商全球 SD-RTN 网络OpenAI Realtime API 首批官方合作伙伴。Conversational AI Engine把语音 Agent 的四层实时传输 / Agent 运行时 / AI 模型 / 端上体验打包好开发者不用自己拼 ASR LLM TTS 打断 传输。一句话定位用来快速搭语音智能体的实时对话引擎。2.2 技术栈解析RTC / WebRTC实时传输层走 UDP、低延迟、能丢包容忍还能顺带做回声消除和降噪是「边说边听、随时打断」的底子。STT语音转文字本次用 DeepgramAgora 托管。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.pyfrom agora_agent.agentkit.vendorsimportOpenAI, DeepgramSTT, MiniMaxTTS sttDeepgramSTT(modelnova-3,languageen)llmOpenAI(modelgpt-4o-mini,input_modalitiesINPUT_MODALITIES,...)ttsMiniMaxTTS(modelspeech_2._6_turbo,voice_idEnglish_captivating_female1)agora_agentagora_agent.with_stt(stt).with_llm(llm).with_tts(tts)最后那行 .with_stt().with_llm().with_tts() 把三段拼成一条流水线——想换厂商替换对应那个 vendor 就行这就是级联式「每层可换」的好处。多模态的关键在 input_modalitiesINPUT_MODALITIES它定义在 vision_config.py#server/src/vision_config.pyINPUT_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.pyself.openai_api_keyos.getenv(OPENAI_API_KEY)# optional — Agora 托管self.openai_modelos.getenv(OPENAI_MODEL,gpt-4o-mini)llmOpenAI(api_keyself.openai_api_key,modelself.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 SkillsClaude Code plugin管「怎么搭」——帮助手选对 starter 和 setup 顺序。Agora MCP管「查文档」——实时拉最新官方文档。后两个是给 Claude Code 这个 AI 助手加的 buff它替你查文档、按官方流程走你只要给方向。4.1 工具安装Agora CLI管账号 / 凭证curl-fsSLhttps://dl.agora.io/cli/install.sh|shcdC:\Users\你的用户\bin agora--help# 验证装好#Windows PowerShell 备选irm https://dl.agora.io/cli/install.ps1|iex如果想全局执行agora --help可以添加一下系统环境变量Agora Skills MCP在 Claude Code 里装Skills 会自动带上 MCP#需要先执行Claude code启动/plugin marketplaceaddAgoraIO/skills /plugininstallagora验证整体环境agora doctor4.2 登录 一句 prompt让助手自己搭先登录拿凭证CLI 会弹浏览器授权agora login弹出一个链接需要登录一下然后给 Claude Code 一句针对 vision recipeUse 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 仓库gitclone https://github.com/AgoraIO-Conversational-AI/recipe-agent-visioncdrecipe-agent-vision#2. 装依赖web Python venvbun run setup#3. 登录 写凭证agora login agora project use# 选一个 projectagora projectenvwriteserver/.env.local#4. 跑起来bun run dev打开 http://localhost:3000 → Start Conversation → 允许摄像头。五、两条路线之争级联 vs 端到端 Realtime5.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 写的——它调 python3Windows 上只有 python还 source venv/bin/activateWindows 的 venv 目录是 Scripts/ 不是 bin/。两者在 Windows Git Bash 下都不兼容。解决绕开脚本手动建 venv 装依赖cdserver python-mvenv venvsourcevenv/Scripts/activate python-mpipinstall-rrequirements.txtbun run dev 同理会踩它的 dev:backend 也写了 venv/bin得手动分跑 backend 和 frontend#backend一个终端cdservervenv/Scripts/python src/server.py#frontend另一个终端cdwebAGENT_BACKEND_URLhttp://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 projectenvwriteserver/.env.local--projectproject-id或先绑定一次agora project use6.3 机器没摄像头DEVICE_NOT_FOUND OBS 两连坑页面起来了Console 报 AgoraRTCError DEVICE_NOT_FOUND。原因台式机 / 远程桌面 / 虚拟机 often 没有摄像头硬件。注意这是「设备没找到」不是「权限被拒」——权限被拒会是 PERMISSION_DENIED。解决装 OBS Virtual Camera 当虚拟摄像头但有两个连环坑OBS 要以管理员身份运行再点「启动虚拟摄像机」驱动才注册普通权限会被静默拒绝系统里查不到设备。注册后浏览器要完全重启杀掉残留进程再开否则设备列表是旧的、识别不到 OBS Virtual Camera。七、评价看得有多准、适合干嘛7.1 好的地方零 key 真的开箱即用——不用申请 OpenAI / Deepgram / MiniMax 的 key注册 Agora 账号、CLI 写个凭证就能跑门槛低得有点不真实。多模态接入很省心——前端推一路 RTC trackusePublish后端一句 input_modalities[“text”,“image”]剩下 Agora 云帮你把摄像头帧喂给 LLM不用自己写图像上传那一坨。流水线可换可调——STT / LLM / TTS 是三个独立 vendor想换厂商换一个就行这是级联式的好处。为体验做了底层优化——代码里能看到为低延迟选了 chorus profile、为可打断配了 turn_detectionVAD。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 能力就行这正是这种架构的乐趣。