LiveKit Agents：开源实时语音/视频 AI Agent 框架

为什么需要 LiveKit Agents：实时语音 Agent 的百行代码工程化

传统方式构建一个语音助手，需要自己打通六层链路：第一层是 WebRTC 信令与媒体传输，保证浏览器/手机与服务器之间的低延迟音视频流；第二层是音频采集与播放，涉及回声消除、噪声抑制；第三层是 VAD（语音活动检测，用于判断用户什么时候开始/结束说话）；第四层是 STT 流式转写；第五层是 LLM 推理与工具调用；第六层是 TTS 流式合成。任何一层出问题都会导致对话卡顿或断连，团队往往要投入数周才能跑通一个可演示的 Demo。

LiveKit Agents 把上述链路封装为声明式 API。开发者只需要实现 Agent 逻辑——设定 system prompt、选择 STT/LLM/TTS 提供商、配置 VAD 灵敏度，其余传输、调度、重连、打断处理全部由框架接管。管道内的每个环节支持热替换：比如把 OpenAI TTS 换成 ElevenLabs，只需改一行代码，不用动传输层。

与同类框架相比，LiveKit Agents 的气质差异在于“传输自研 + 能力开放”：WebRTC SFU 是自家开源产品，不依赖第三方传输供应商；语音管道层则保持插件化，不锁定任何模型厂商。对于需要完全掌控数据链路和部署位置的生产团队，这是最贴近“基础设施自有”的方案。

安装与环境配置：5 步就绪

LiveKit Agents 的运行前提是存在一个可连接的 LiveKit Server——它负责信令和媒体转发，Agent 本身以 Worker（工作进程）模式运行，从服务端拉取会话任务。开发模式下可用本地二进制快速启动。

步骤一：安装 Python 包。 需要 Python 3.9+，核心包与插件包分开安装：

步骤二：安装 LiveKit Server 与 CLI。 macOS 直接用 Homebrew，Linux 从 GitHub Releases 下载二进制：

步骤三：启动开发服务器。 --dev 模式会生成临时 API 密钥并打印出来，供本地连接使用：

步骤四：配置环境变量。 根据你使用的插件，导出对应服务商密钥：

步骤五：验证安装。 确认核心包可导入并查看版本：

pip install livekit-agentspip install livekit-plugins-openai livekit-plugins-deepgram livekit-plugins-silero

brew install livekit        # macOS# Linux 用户从 https://github.com/livekit/livekit/releases 下载后放入 PATH

livekit-server start --dev

export LIVEKIT_URL=ws://localhost:7880export LIVEKIT_API_KEY=devkeyexport LIVEKIT_API_SECRET=secretexport OPENAI_API_KEY=sk-...export DEEPGRAM_API_KEY=...

python -c "from livekit import agents; print('LiveKit Agents OK')"pip show livekit-agents | grep -E "Name|Version"

快速上手：10 分钟跑通第一个语音 Agent

最小可用方案分三步：写一个 Agent Worker 脚本 → 以开发模式运行 → 在浏览器 Playground 里对话验证。官方 Playground（agents-playground.livekit.io）是一个免部署的测试页面，连接本地 dev server 后即可用麦克风与 Agent 对话。

第一步：创建 voice_agent.py，定义一个 Agent 实例——Agent 负责把 STT/LLM/TTS/VAD 组装成完整语音管道，AgentSession 负责管理会话生命周期；第二步：运行 python voice_agent.py dev，脚本会注册到本地 LiveKit Server 等待任务；第三步：打开 Playground 页面，填入 dev server 输出的 URL/Key/Secret，点击连接并开始说话。

运行命令：

运行后终端会显示 "Worker started"。连上 Playground 并说话，Agent 会在约 1 秒内回复。进阶技巧：在 Agent 构造函数中传入 fnc_ctx 注册工具函数，即可让语音助手执行查天气、查订单等真实操作；把 deepgram.STT() 换成 openai.realtime.RealtimeModel() 可切换到端到端实时语音模型。

# voice_agent.py —— 基于 LiveKit Agents v2 APIimport asynciofrom livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, clifrom livekit.plugins import deepgram, openai, silero  async def entrypoint(ctx: JobContext):    # 组装语音管道：Deepgram 转写 → GPT-4o 推理 → OpenAI TTS 合成    agent = Agent(        instructions="You are a concise, friendly voice assistant.",        stt=deepgram.STT(),        llm=openai.LLM(model="gpt-4o"),        tts=openai.TTS(),        vad=silero.VAD.load(),    )    session = AgentSession(agent=agent)    await session.start(room=ctx.room)    # 进入房间后主动发起一句问候    await session.generate_reply(instructions="Say a brief greeting and ask how you can help.")  if __name__ == "__main__":    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

python voice_agent.py dev

核心能力详解：5 大支柱

支柱一：实时语音管道。 框架以流式方式串联 STT → LLM → TTS，音频按帧处理而非等待完整句子，因此首字响应可做到亚秒级。VAD 驱动打断体验：检测到用户开始说话时，TTS 立即停止播放，实现自然的“抢话”交互。管道组件全部可替换，同一个 Agent 可以切换不同厂商。

支柱二：多 Agent 编排与会话管理。 v2 引入 AgentSession 统一管理会话状态、对话历史、工具调用与回复生成。一个房间可部署多个 Agent，按需切换发言者，适合面试模拟、双角色对话等场景。会话上下文在房间生命周期内持续维护，支持插件式记忆扩展。

支柱三：官方插件生态。 官方维护 12+ 插件包：OpenAI（含 Realtime API、Chat、TTS）、Deepgram、ElevenLabs、Google Gemini Live、Anthropic、Azure、Groq、AWS（Bedrock/Polly/Transcribe）、Cartesia、Rime 等。选用方式统一——例如语音转写用 livekit-plugins-deepgram 的 deepgram.STT()，大模型用 openai.LLM()，按需替换即可。

支柱四：Worker 部署模型。 Agent 以独立进程运行，通过 WebSocket 从 LiveKit Server 拉取“用户进入房间”这类作业（Job）。多实例 Worker 可横向扩展——服务端按负载分发任务，单 Worker 崩溃不影响其他会话。进程级隔离让每个 Agent 的依赖、环境变量可以独立管理。

支柱五：SIP 电话接入。 通过 SIP 中继，语音 Agent 可接入 PSTN（公共电话网）——用户用普通手机号即可拨入对话。支持 Twilio、Telnyx 以及自有运营商线路，官方提供 inbound/outbound 通话示例。这让客服机器人、电话助手类产品无需开发 App 即可触达用户。

生产部署与监控：从上线到运维

部署方式一：自托管 LiveKit Server。 生产环境建议用 Docker 或 Kubernetes 部署 LiveKit Server 集群，核心配置点包括：ICE 服务器列表（用于 NAT 穿透）、TURN 服务（网络受限环境的媒体中继）、TLS 证书（WebRTC 强制要求 HTTPS/WSS）、区域就近接入。Agent Worker 作为独立服务部署在靠近 LiveKit Server 的机房以降低延迟。官方提供完整的 Docker Compose 与 Helm Chart 参考配置。

部署方式二：LiveKit Cloud 托管。 若不想运维 SFU，可直接使用 LiveKit Cloud 提供信令与媒体服务，Agent Worker 仍运行在你自己的服务器上，通过 API Key 认证接入云端。Cloud 附带自动扩缩容、全球边缘节点和内置观测面板，适合快速上线验证。注意 Cloud 仅托管传输层，STT/LLM/TTS 的 API Key 和成本仍由你自行管理。

可观测性。 LiveKit Server 暴露 Prometheus Metrics（在线房间数、连接数、带宽、ICE 失败率）；Agent Worker 侧通过标准 logging 输出会话与管道事件，配合 livekit-cli 可实时查看房间内音视频流状态。生产环境建议接入集中式日志系统，并设置告警规则监控“连接失败率”与“会话平均时长”两个核心指标——前者反映网络质量，后者反映用户粘性。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>升级陷阱：v2 与 v1 API 完全不兼容，v1 的 PipelineAgent、JobProcess 均已废弃；升级前锁定依赖版本并核对官方迁移文档，切勿直接替换包版本。</li><li>成本陷阱：STT/TTS 按调用时长计费且语音流量远高于文本，上线前用官方用量计算器估算每分钟成本，并为每个服务商设置预算告警。</li><li>网络陷阱：自建 Server 必须配置 TURN/ICE，否则跨运营商或企业内网环境下媒体连接会频繁中断；先用 LiveKit Cloud 或本地 docker-compose 验证网络拓扑再上生产。</li><li>调参陷阱：VAD 灵敏度直接影响打断体验，阈值过高会因环境噪声误打断 TTS，过低则用户抢话无响应；需按实际麦克风与场景音频反复测试。</li></ul>

版本迭代

LiveKit Agents 从 2024 年初的预览演进到 9 月 1.0 GA，再于 2025 年 1 月发布 2.0 全面重写——核心路线是从“单体管道”转向“模块化插件 + 显式会话管理”，并同步布局 JavaScript 生态（AgentJS 1.0）。

AI 应用场景

常见误区

面试题

参考来源

• webpageGitHub: livekit/agents源码、Changelog 与官方示例
• webpage官方示例仓库语音、SIP 电话、会议转录等可运行示例