LiveKit Agents 实时语音 Agent 实战从本地调试到生产部署的路径【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agentsLiveKit Agents 是一个用 Python 构建实时语音 AI 应用的框架负责把 STT、LLM、TTS 串成完整的语音对话流水线。本文带你跑通第一个语音 Agent看清日常开发工作流以及上生产前必须改的几件事。⚡ 30秒跑通第一个语音 Agent先说结论一个能听、能想、能说的 Agent核心代码就三行模型配置。直接复用仓库里的示例最快参考 examples/voice_agents/basic_agent.pygit clone https://gitcode.com/GitHub_Trending/agen/agents.git cd agents # LiveKit 连接信息 模型提供商的 key export LIVEKIT_URL... LIVEKIT_API_KEY... LIVEKIT_API_SECRET... export DEEPGRAM_API_KEY... OPENAI_API_KEY... CARTESIA_API_KEY... uv sync --all-extras --dev # 项目用 uv 管理依赖 uv run python examples/voice_agents/basic_agent.py dev运行后控制台会提示启动了一个本地 LiveKit 房间用任意 LiveKit 客户端网页 Demo、桌面端加入房间就能和 Agent 语音对话。它用的模型组合是stt inference.STT(deepgram/nova-3, languagemulti) llm inference.LLM(openai/gpt-4.1-mini) tts inference.TTS(cartesia/sonic-3, voice...)如果这一步卡住了比如房间起不来、没声音、key 报错看下一节。 日常开发工作流拆解这个仓库本身就是一个多包 workspacelivekit-agents/核心框架 60 多个livekit-plugins/*所以它的 makefile 把开发动作全固化成了命令。按一次真实提交的顺序走搭好本地开发环境make install # 等价于 uv sync --all-extras --dev make doctor # 检查 uv/python/git 是否就位、livekit 装没装doctor不只查工具版本还会告诉你当前用的是 PyPI 版还是本地编辑版 livekit这对排查我改的代码为什么没生效这类问题非常有用。提交前过质量门禁make check # format-check lint type-check make fix # 一键修掉格式和 lint 问题背后是 ruff 管格式和 lintmypy 管类型走 scripts/check_types.py。建议把make check养成肌肉记忆别等 CI 红灯才回头改。拉起隔离的测试环境集成测试放在 tests/ 目录用 Docker 一键拉起cd tests make test # 起容器 → 装依赖 → 跑 pytest → 自动拆除看 tests/docker-compose.yml 会发现一个有意思的设计容器里跑 Toxiproxy 故障代理把所有模型提供商的域名api.openai.com、api.deepgram.com 等劫持到代理上。也就是说测试可以故意断网、加延迟验证 Agent 在云服务抖动时的表现。纯本地能跑的用make unit-tests不需要任何云账号。锁定和切换依赖版本仓库根目录的uv.lock锁定了全部依赖团队环境天然一致。需要换 livekit 客户端 SDK 版本时make link-rtc-version VERSION0.18.0 # 装指定 PyPI 版本 make unlink-rtc # 恢复 PyPI 最新版 make status # 随时查看当前链接状态 上生产前要改的 3 件事问题 1怎么打包参考 examples/Dockerfile-example 这个模板python-slim 基础镜像、非 root 用户运行、PYTHONDONTWRITEBYTECODE和PYTHONUNBUFFERED两个环境变量别删后者避免进程崩溃时日志被缓冲吞掉。问题 2模型文件什么时候下载Dockerfile 里有一行python -m livekit.agents download-files把 VAD 等本地模型在构建期就拉进镜像。这样容器启动即就绪不用等运行时下载、也不怕线上没外网。问题 3密钥怎么管理看 tests/docker-compose.yml 的 environment 段就是标准做法所有 key 通过环境变量注入代码里不出现任何明文。生产上换成 K8s Secret 或密钥管理服务方式不变。 排查卡点的快捷方式工具解决什么一条命令make doctor本地环境缺什么、装没装对make doctormake statuslivekit 是 PyPI 还是本地版、FFI 库来自哪make statusmake unit-tests不依赖云服务的核心逻辑回归make unit-testsToxiproxy 测试云服务抖动时 Agent 的容错行为cd tests make testLK_DUMP_TTS1TTS 音频落盘回放定位说错了/没声音环境变量见 tests/docker-compose.yml日志方面示例里用ctx.log_context_fields给每条日志挂 room 等上下文字段配合metrics.log_metrics输出结构化指标线上排障时按字段过滤即可不用人肉翻日志。 下一步往哪走如果你要和某个特定版本的 livekit SDK 对齐用make link-rtc-version VERSIONx.y.z别手改pyproject.toml。如果你要改 FFI 层的 Rust 代码走make link-rtc-local需要 cargo它会提示你导出LIVEKIT_LIB_PATH。如果你想学更复杂的会话流程多 Agent 交接、下单、预约别自己造轮子直接读 examples/ 下的 drive_thru、frontdesk、warm-transfer它们各自带完整测试。本文覆盖了从跑通示例、本地工作流到容器化部署的完整路径。仓库里每个 example 都是可运行的建议挑一个跑起来遇到具体问题可以看看对应目录的 README 和测试文件。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考