LiveKit Agents 实战：本地跑通语音 Agent 的 5 个工程动作
【免费下载链接】agentsA framework for building realtime voice AI agents 🤖🎙️📹项目地址: https://gitcode.com/GitHub_Trending/agen/agents
LiveKit Agents 是构建实时语音 AI Agent 的开源框架，覆盖 STT、LLM、TTS 全链路和工具调用。这篇文章不讲架构概念，只带你走一遍从 clone 到 demo 跑通、测试跑顺的工程动作，全部可以在你自己的机器上复现。
用这类项目最容易卡住的是三个地方：环境、第一个 demo、测试怎么信。下面按这个顺序讲，外加两个实际会遇到的取舍。
🛠 第一个坑：依赖装乱，先跑 make doctor
clone 下来之后别急着uv pip install，根目录的 makefile 已经把流程包好了：
git clone https://gitcode.com/GitHub_Trending/agen/agents cd agents make install make doctormake install本质是uv sync --all-extras --dev，仓库里带uv.lock，版本和团队完全一致。make doctor会检查 uv、python、git 是否就位，.venv存不存在，livekit装的是 PyPI 版还是本地 editable 版，任何一项缺失就以非零退出。根目录pyproject.toml里定义了 uv workspace，livekit-agents和多个examples/*都是成员，所以一次 sync 就把所有示例的开发依赖装齐了。我的建议是新机器上先通读make doctor的输出，再看报错堆栈。
3 条命令跑通第一个 demo
cp examples/.env.example examples/.env uv run examples/voice_agents/basic_agent.py console把LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET填进.env后，第二条命令就能在 console 里和语音 Agent 对话，不需要真实声卡。basic_agent.py只有 140 行：一个 Agent 类、一个@function_tool查天气，STT/LLM/TTS 全走inference统一入口，模型名写成deepgram/nova-3这种形式，不用按厂商分别申请 key。我一般先跑这个最薄的 demo，再回头读livekit-agents源码——Agent、AgentSession、JobContext三个对象在代码里各被调用的地方看一遍，比直接啃 300 行框架内部代码划算。
make test 失败，先看 tests/ 的两级测试
cd tests make test测试分两级。快的用根目录make unit-tests，跑pytest --unit --audio_eot，这两类标记的测试不碰任何云账号，是纯本地 hermetic 测试，可以直接放 CI。全量的在 tests/Makefile 里，只有up、test、down三个目标：test会先等 8474 端口的 toxiproxy 就绪，再进 app 容器执行uv sync后跑 pytest，结束自动 down。tests/docker-compose.yml把livekit-agents、livekit-plugins、tests三个源码目录挂载进容器，改代码不用重建镜像；文件里那 28 个*_API_KEY全部从仓库根.env透传，你跑 demo 时已经填过 key，make test不用再注入任何东西。测试挂了，我一般先读--tb=short的 traceback：连接被拒或 401 是环境问题，断言失败才是代码问题，别先怀疑本地机器。
自己起项目时，复制哪个 examples 目录
别复制livekit-agents源码，直接拷一个自包含的示例目录。每个 example 都有自己的pyproject.toml和Dockerfile，拷走之后uv sync加uv run agent.py console就能跑，依赖全来自 PyPI；要部署就lk agent deploy .，直接拿目录里的 Dockerfile 构建。我挑目录的经验：验证语音主链路选voice_agents/；验证工具调用加策略约束选hotel_receptionist/，它的policies/里是一整套.md策略文件；验证数据落库选drive_thru/，带database.py和order.py。想看测试怎么组织，翻examples/homepage/tests/，unit 和 evals 是分开的。
livekit-rtc 用 PyPI 版还是本地源码
默认用 PyPI wheel，别动。只有要改 Rust FFI 层时才链接本地：make link-rtc下载官方 FFI 产物并uv add --editable指向本地python-sdks；make link-rtc-local则是cargo build --release -p livekit-ffi自己编，需要 cargo，没装的话make doctor会给出警告。切换后跑make status确认，输出里会显示LOCAL (editable)或PyPI加版本号；收尾用make unlink-rtc还原。本地/远程切换 makefile 里给了这 4 个专门目标，别手改pyproject.toml，容易改一半。
回到终端：先在你机器上跑一遍make doctor，然后进examples/voice_agents/把那个 140 行的basic_agent.py在 console 里聊一轮，跑通了再去tests/里看make test的全景。
【免费下载链接】agentsA framework for building realtime voice AI agents 🤖🎙️📹项目地址: https://gitcode.com/GitHub_Trending/agen/agents
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
