用 Vision Agents 构建你的第一个语音视频 AI Agent从零到可对话的完整实战指南【免费下载链接】Vision-AgentsOpen Vision Agents by Stream. Build voice and vision agents quickly with any model or video provider. Uses Streams edge network for ultra-low latency.项目地址: https://gitcode.com/GitHub_Trending/vi/Vision-Agents导读本文以 Vision Agents 仓库中第一个入门示例examples/01_simple_agent_example为主线完整演示如何用 Python 搭建一个能够「听清用户说话 → 交给大模型理解 → 用自然语音回复」的视频 AI Agent并运行在 Stream 的低延迟边缘网络上。读完本文你将掌握Agent 的核心组件edge / LLM / STT / TTS / turn detection如何组装、如何通过 CLI 一键运行并打开浏览器 Demo UI、如何注册自定义工具函数、如何改用 Realtime 模型大幅简化架构以及如何用测试框架验证 Agent 行为。一、这个示例解决什么问题examples/01_simple_agent_example是 Vision Agents 仓库中最基础的入门示例它的目标是展示构建一个「最小可运行」的语音视频 AI Agent 需要哪些步骤。示例 Agent 具备以下能力见 simple_agent_example.py 顶部的模块注释听通过 Deepgram 将用户的语音实时转写为文本STT想通过 Gemini 大模型处理对话、决定回复内容LLM并支持函数调用如查询天气说通过 ElevenLabs 把回复合成为自然语音TTS连通过 Stream 的边缘网络完成音视频传输Edge切换通过 Deepgram 的eager_turn_detection实现低延迟的说话人停顿检测。整个链路是一条「Eager turn taking STT → LLM → TTS」的流式流水线专门为追求最快响应速度的对话场景设计。二、环境准备与安装2.1 前置条件根据示例文档运行本示例需要Python 3.13 或更高版本示例的 pyproject.toml 中声明requires-python 3.13,3.14以下服务的 API KeyOpenAILLM示例源码实际默认使用 Gemini但插件已随包安装ElevenLabs文本转语音TTSDeepgram语音转文本STTStream视频/音频基础设施需要STREAM_API_KEY与STREAM_API_SECRETSmart Turnfal.ai 上的模型可选用于说话人停顿检测。2.2 安装依赖进入示例目录使用uv同步依赖示例与核心包、各插件均通过[tool.uv.sources]以可编辑路径方式关联到仓库本体因此不需要单独安装 Vision Agentscd examples/01_simple_agent_example uv sync从 pyproject.toml 可以看到本次安装会拉入vision-agents核心包以及 deepgram、elevenlabs、getstream、openai、gemini、smart-turn、anthropic、cartesia、vogent 等插件包——这意味着你可以随时在代码中切换任意供应商的实现。2.3 配置 API Key在示例目录下创建.env文件代码通过load_dotenv()自动加载OPENAI_API_KEYyour_openai_key ELEVENLABS_API_KEYyour_11labs_key DEEPGRAM_API_KEYyour_deepgram_key STREAM_API_KEYyour_stream_key STREAM_API_SECRETyour_stream_secret三、运行 Agent一条命令启动uv run simple_agent_example.py run命令执行后Agent 会依次完成四件事创建一个视频通话video call在浏览器中打开 Demo UI加入通话并开始监听对你的语音输入做出响应。3.1 CLI 背后的实现入口在 simple_agent_example.pyif __name__ __main__: Runner(AgentLauncher(create_agentcreate_agent, join_calljoin_call)).cli()Runner.cli()基于 Click 实现见 runner.pyrun子命令支持以下可选参数可用于调试与自定义参数默认值说明--call-typedefault视频通话的类型--call-id自动生成 UUID指定通话 ID--debug关闭开启 asyncio 调试模式--log-levelINFO日志级别DEBUG/INFO/WARNING/ERROR/CRITICAL--no-demo关闭禁用自动打开浏览器 Demo UI--video-track-override无用本地视频文件替代输入视频轨道便于无摄像头调试--no-splash关闭隐藏终端启动横幅例如只想在终端里测试、不弹浏览器uv run simple_agent_example.py run --no-demo3.2 运行时的幕后流程从 runner.py 的run()实现可以看到若未指定call_id自动生成str(uuid4())调用AgentLauncher.start()完成组件预热warmup日志会输出「 Launching agent...」与「✅ Agent warmed up and ready」通过start_session(call_id, call_type)启动会话——AgentLauncher会先launch()创建 Agent再以独立异步任务执行join_call见 agent_launcher.py除非传入--no-demo否则调用edge.open_demo_for_agent(agent, call_type, call_id)在浏览器打开 Demo UIsession.wait()阻塞直到通话结束收到 CtrlC 或CancelledError时优雅关闭。其中「预热」是一个值得注意的工程细节AgentLauncher.warmup()会创建一个 dry-run 的 Agent并并行对其 LLM、TTS、STT、turn detection、processor 等所有可预热组件调用warmup()见 agent_launcher.py显著降低首包延迟。四、代码走读组装一个 Agent4.1 核心构建函数示例的create_agent见 simple_agent_example.py是组装 Agent 的完整范例async def create_agent(**kwargs) - Agent: llm setup_llm() agent Agent( edgegetstream.Edge(), # 低延迟边缘网络 agent_userUser(nameMy happy AI friend, idagent), instructionsINSTRUCTIONS, processors[], # processors 可拉取额外数据、检查图像/音频或转换视频 llmllm, ttselevenlabs.TTS(model_ideleven_flash_v2_5), sttdeepgram.STT(eager_turn_detectionTrue), ) return agent各组件职责如下edge低延迟音视频传输层。使用getstream.Edge()官方提供 React、iOS、Android、RN、Flutter 等客户端 SDK 与之对接agent_userAgent 的身份名称与 ID类型为 User 数据类含id、name、image、custom元数据字段instructions系统提示词决定 Agent 的行为方式支持file.md引用外部指令文件见 Agent 构造函数llm对话大脑示例默认gemini.LLM(gemini-flash-lite-latest)追求快速响应tts把回复合成为语音示例选用 ElevenLabs 的eleven_flash_v2_5模型stt把用户语音转成文本示例开启eager_turn_detectionTrueturn_detection检测用户何时说完话。示例故意不单独配置——Deepgram 自带端点检测代码注释「smart turn and vogent are supported. not needed with deepgram (it has turn keeping)」。4.2 关于eager_turn_detection的取舍示例特意把deepgram.STT(eager_turn_detectionTrue)与一行注释放在一起eager_turn_detection - lower latency (but higher token usage)。查看 deepgram_stt.py 的实现可以发现开启该选项后若未显式指定eager_eot_thresholdSDK 会自动把它初始化为一个更小的端点阈值end-of-turn threshold从而更早地判定用户说完话让 LLM/TTS 提前启动换来更低响应延迟代价是更频繁触发推理、消耗更多 token。这是「延迟 vs 成本」之间一个很直观的工程权衡。4.3 加入通话并运行join_call见 simple_agent_example.py演示了 Agent 的核心生命周期async def join_call(agent: Agent, call_type: str, call_id: str, **kwargs) - None: call await agent.create_call(call_type, call_id) # 让 Agent 加入通话/房间 async with agent.join(call): # 方式一使用 agent.simple_response 快速引导对话 await agent.simple_response(tell me something interesting in a short sentence) # 方式二需要更精细控制时调用原生 openAI create_response可携带文本图片 # await llm.create_response(input[...]) # 一直运行到通话结束 await agent.finish()三步流程非常清晰创建通话agent.create_call(call_type, call_id)其中call_id建议使用唯一 ID加入并运行async with agent.join(call)作为异步上下文管理器管理连接生命周期等待结束await agent.finish()阻塞直到通话结束。注意示例代码里的完整create_call是agent.edge.client.video.call(default, str(uuid4()))README 中的写法而源码中封装为agent.create_call()。另外根据 Agent 类文档 的提醒不要复用 Agent 对象每次通话都应创建新实例。4.4 运行自定义指令文件instructions.md 展示了如何通过指令文件注入「人格」always mention how bad the weather is in amsterdam结合setup_llm()中注册的天气函数这个 Agent 会变成一个「永远吐槽阿姆斯特丹天气」的趣味助手——这正是 README 中「Edit theinstructionsparameter to change how your agent behaves」的落地示例。五、给 Agent 添加工具函数注册示例通过装饰器为 LLM 注册自定义工具见 simple_agent_example.pydef setup_llm(model: str gemini-flash-lite-latest) - LLM: llm gemini.LLM(model) llm.register_function(descriptionGet current weather for a location) async def get_weather(location: str) - Dict[str, Any]: return await get_weather_by_location(location) return llmllm.register_function(description...)会把函数签名与描述同步给模型模型在对话中自主决定何时调用、传入什么参数。天气数据的真实获取逻辑在核心包的vision_agents.core.utils.examples.get_weather_by_location中Agent 拿到返回结果后继续组织回复。这套机制是后面「测试」章节验证的重点。六、原生 API 访问不绕路的灵活性Vision Agents 并不把供应商能力「锁死」在抽象层里而是直接暴露原生 LLM API。README 展示了 OpenAI 风格的多模态输入await llm.create_response(input[ { role: user, content: [ {type: input_text, text: Tell me a poem}, {type: input_image, image_url: https://...} ] } ])示例源码的注释里也保留了同样的用法把文本与input_image一起传入即可让模型「看着图片作诗」。这意味着当你需要模型原生能力如图像理解、结构化输出时可以随时绕过框架的默认对话封装直接调用底层 API。七、进阶用 Realtime 模型简化架构如果你希望代码更精简、延迟更低可以换用 Realtime 模型如 OpenAI Realtime 或 Gemini Live。这类模型内部自行完成语音识别与语音合成你不再需要配置 tts、stt、vad 组件agent Agent( edgegetstream.Edge(), agent_userUser(nameMy happy AI friend, idagent), instructionsYoure a video AI assistant..., llmopenai.Realtime() # 无需单独的 tts/stt/vad )这印证了 Agent 构造函数 的注释stt、tts、turn_detection在使用 Realtime LLM 时均非必需。示例源码同样在注释中保留了# llmopenai.Realtime()的备选方案。README 指出可参考examples/02_golf_coach_example查看 Realtime 模型的完整用法。八、组件可插拔按需替换Vision Agents 的插件体系让「换供应商」变得非常廉价各插件均以vision-agents-plugins-*独立包随示例安装LLMopenai.LLM(...)、gemini.LLM(...)、openai.Realtime()、gemini.Realtime()等TTSelevenlabs.TTS()、kokoro.TTS()等STTdeepgram.STT()等Turn Detectionsmart_turn.TurnDetection()、vogent.TurnDetection()等参考 pyproject.toml 的依赖列表。换用不同供应商只需修改Agent(...)里对应的构造参数Agent 整体架构保持不变。九、给 Agent 增加处理器ProcessorsAgent构造函数接收processors参数见 agents.py其用途注释写得很清楚处理器可拉取额外数据、检查图像/音频数据、或转换视频处理器产出的状态会传递给 LLM。在示例中processors[]为空列表——因为它只做纯语音对话。README 建议查看 golf coach 示例examples/02_golf_coach_example那里演示了用 YOLO 做目标检测的 processor 用法让 Agent 具备「看见」能力。这正是从「语音 Agent」迈向「视觉 Agent」的扩展点。十、运行集成测试验证行为示例自带两个集成测试test_simple_agent.py需要GOOGLE_API_KEY通过 pytest 的-m integration标记运行cd examples/01_simple_agent_example uv run py.test -m integration测试用例展示了vision_agents.testing测试工具包的典型用法TestSessionLLMJudgetest_greeting用session.simple_response(Hey there!)让 Agent 打招呼断言没有产生函数调用再用LLMJudge评判回复是否为「友好、简短」test_weather_tool_call问「Berlin 天气如何」断言 Agent 调用了get_weather且参数为{location: Berlin}并评判回复是否汇报了天气test_weather_tool_call_mocked用session.mock_functions({get_weather: lambda **_: {temp_f: 55, condition: rainy}})模拟工具返回值再用AsyncMock验证工具被调用一次、入参正确、输出被透传——这是不依赖外部天气服务的确定性测试写法。值得注意的是测试默认模型为gemini-3-flash-preview可通过VISION_AGENTS_TEST_MODEL环境变量覆盖并会在缺少GOOGLE_API_KEY时自动跳过便于 CI 环境中安全执行。十一、总结与下一步本文用最短路径完成了第一个可对话的语音视频 AI Agentuv sync装依赖 → 写.env配密钥 →uv run simple_agent_example.py run一键运行浏览器 Demo UI 随即打开Agent 加入通话开始倾听与回应。随后我们深入到源码层理解了AgentLauncher的预热机制、Runner的 CLI 参数、eager_turn_detection的延迟-成本权衡以及函数注册、原生 API、Realtime 简化、processor 扩展和测试验证等进阶能力。如果想继续深入推荐按顺序探索02_golf_coach_example在 Agent 中接入 YOLO 等视觉处理器体验真正的「视觉 Agent」03_phone_and_rag_example电话接入与知识库检索RAG根目录 README.md 与 CHANGELOG.md了解 Vision Agents 的完整功能矩阵与演进历史plugins 目录查看全部供应商插件的实现与各自 README。【免费下载链接】Vision-AgentsOpen Vision Agents by Stream. Build voice and vision agents quickly with any model or video provider. Uses Streams edge network for ultra-low latency.项目地址: https://gitcode.com/GitHub_Trending/vi/Vision-Agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
