企业官网建设流程全解析

5 步跑通你的第一个实时语音 AI 智能体：LiveKit Agents 上手实战

【免费下载链接】agentsA framework for building realtime voice AI agents 🤖🎙️📹项目地址: https://gitcode.com/GitHub_Trending/agen/agents

LiveKit Agents 是一个开源的实时语音 AI 智能体框架，几十行 Python 代码就能组装出会听、会说、还能打电话的智能体。这个仓库围绕一件事组织：让你从git clone到生产级语音智能体走最短路径。下面按"拿到仓库 → 本地跑通 → 质量门禁 → 容器化部署"的顺序，把每步怎么做讲清楚。

克隆仓库并 5 分钟内跑通第一个语音智能体

克隆仓库并装好依赖：

git clone https://gitcode.com/GitHub_Trending/agen/agents cd agents && make install

make install实际执行的是uv sync --all-extras --dev。uv 是新一代 Python 依赖管理器，比 pip 快得多；根目录的uv.lock锁死了全部依赖版本，所以每个人的环境都能保持一致。

接着配密钥：把examples/.env.example复制为examples/.env，填入LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET三个值，即 LiveKit Cloud 或自建 LiveKit 服务的凭据。

然后启动第一个智能体：

uv run examples/voice_agents/basic_agent.py console

console是终端模式：智能体直接对着你的麦克风说话和听声，不需要 LiveKit 服务器，也不需要客户端 App，是验证"我的环境没装坏"的最快方式。basic_agent.py 只有 140 来行，读完你会清楚 STT（语音转文本）、LLM（大模型）、TTS（文本转语音）三件套是怎么被组装进一个会话的。

用 console、dev、start 三个模式从终端走向生产

同一个智能体脚本支持三种运行模式，切模式不用改代码：

• console：本地调试，麦克风直连，不碰任何服务器；
• dev：启动 AgentServer 并支持热重载，智能体加入实时房间，网页、手机、电话端任何 LiveKit 客户端都能进来和它对话；
• start：生产模式，开启生产级优化。

日常节奏就是：console里快速验证对话逻辑，调稳后切dev连真房间联调，最后用start上线。

想用自己的模型供应商密钥而不走 LiveKit Inference，示例文件里已把改法注释好——把stt=、llm=、tts=三行换成openai.LLM(...)、deepgram.STT(...)之类即可。仓库内置 60 多个供应商插件，任意组合、一行切换，这是 examples/ 目录里各场景示例能互相借鉴的原因。

用无云端依赖的单元测试证明智能体行为

LLM 输出天然不确定，"我试了一次没问题"不算通过。框架自带测试体系：在 tests/ 目录里，用result.expect.next_event()断言对话流程，还能用.judge()让另一个 LLM 当裁判打分，判断回复是否达成意图。

本地跑免云端账户的测试集，用根 makefile 里的现成目标：

make unit-tests

它执行pytest --unit --audio_eot，即所有标记为 unit 和 audio_eot 的用例：不花一分钱、几分钟跑完，覆盖音频端点检测、打断恢复、指标上报这些核心行为，也是 CI 用来拦截 PR 的同一道门禁。

一条 make 命令拉起故障注入集成测试环境

单元测试覆盖框架自身；涉及真实网络和服务商的集成测试，项目备好了 tests/docker-compose.yml：一个容器跑 pytest，另一个跑 Toxiproxy——一个"故障注入代理"，通过extra_hosts把各供应商的 API 域名指向它，可以按需模拟超时、抖动、断连。

cd tests make test

一条命令完成构建、等待代理就绪、跑测试、拆环境。tests/Makefile 里源码以卷挂载方式进容器，改了文件立即生效，不用重建镜像；只想跑某个插件的用例就传PLUGIN=openai这样的参数。

推代码前，先跑一遍本地质量门禁：

make check

它连跑 ruff 格式检查、ruff lint 和 mypy 严格类型检查，与 CI 标准一致；格式不对时用make fix一键修复。

一份可直接抄的生产镜像，外加三条立刻能做的建议

最后一步是部署。examples/Dockerfile-example 是官方给的最小生产模板，三个细节值得照抄：基于python:slim保持镜像轻；创建非特权用户appuser运行；构建期执行一次模型预下载：

python -m livekit.agents download-files

它把 VAD、端点检测这类本地模型提前拉进镜像，避免线上首次运行时卡顿。入口就是python myagent.py start。每个示例目录也是独立自足的——拷走它，uv sync后直接跑，lk agent deploy .即可用目录里的 Dockerfile 部署。

读完文章，你可以马上做三件事：

1. 先跑一次make doctor。它把 uv、python、git 是否可用、仓库结构是否完整、livekit 包链接到哪个版本逐项列出，哪项不对就报哪项，省掉大半"装坏了"的排查时间。
2. 把console模式当作第一调试入口。它不依赖任何服务器，大部分环境问题在这一步就能排除，别让故障漏到联调阶段。
3. 每次提交前在本机跑make check和make unit-tests。CI 会做同样的两件事，自己先跑一遍，反馈快得多。

【免费下载链接】agentsA framework for building realtime voice AI agents 🤖🎙️📹项目地址: https://gitcode.com/GitHub_Trending/agen/agents