livekit-agents:用 Python 构建低延迟实时语音 AI Agent 的工业级框架

一句话概括

livekit/agents 是一个专为构建实时（realtime）语音 AI Agent 设计的 Python 框架，基于 WebRTC 实现超低延迟的语音交互，支持 STT → LLM → TTS 全链路编排。该项目已获得 ⭐ 10,460 Stars、🍴 3,124 Forks，采用 Apache-2.0

开源协议，GitHub 地址：https://github.com/livekit/agents 。

为什么值得关注（3 个理由）

1. 真正的实时交互，不是"你说完等 3 秒再回"

大多数语音对话系统采用"录音 → 完整发送 → 等待 TTS 生成 → 播放"的线性流程，延迟通常在 2-5 秒。livekit/agents 基于 WebRTC 协议构建，支持流式音频传输，配合语义话轮检测（Semantic Turn Detection）模型，可以在用户说话间隙的 几百毫秒 内开始响应，体验接近真人对话。

2. 成熟的插件生态，不绑死任何一个模型提供商

框架内置了对 OpenAI、Deepgram、Cartesia、Silero、ElevenLabs、Google Gemini、Perplexity 等主流 STT/LLM/TTS/VAD 插件的原生支持，通过统一的 inference 抽象层切换模型，一条 pip install 即可组合出完整的语音 Agent 管线。这意味着你不需要为了更换 TTS 引擎重写业务逻辑。

3. 生产就绪：调度、伸缩、 telephony 全内置

与许多"能跑 demo"的 AI 框架不同，livekit/agents 内置了 AgentServer 调度器，支持多 Agent 实例并发、任务分发、生产级优化（start 模式），并可通过 LiveKit SIP 模块实现电话呼入/呼出。这使得从开发到上线不需要替换框架。

核心架构分析

整体架构

┌──────────────────────────────────────────────────────────┐│                    客户端 (Web/Mobile/电话)                ││                    LiveKit Client SDK                    │└────────────┬─────────────────────────────────────────────┘             │ WebRTC (音频流 + 数据通道)             ▼┌──────────────────────────────────────────────────────────┐│                   LiveKit Server                         ││              (Go 编写的 WebRTC 媒体服务器)                  │└────────────┬─────────────────────────────────────────────┘             │ Job Dispatch API             ▼┌──────────────────────────────────────────────────────────┐│                    AgentServer                           ││  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  ││  │ Job Queue   │→│ Worker Pool │→│  Agent 实例 × N   │  ││  │ 调度器       │  │ 伸缩管理     │  │ (Python asyncio) │  ││  └─────────────┘  └─────────────┘  └─────────────────┘  │└────────────┬─────────────────────────────────────────────┘             │             ▼┌──────────────────────────────────────────────────────────┐│                    Agent Pipeline                        ││                                                          ││  ┌──────┐    ┌──────┐    ┌────────┐    ┌──────┐        ││  │ VAD  │──→ │ STT  │──→ │  LLM   │──→ │ TTS  │──→ 输出 ││  │(静音  │    │(语音  │    │(对话   │    │(文本  │        ││  │检测) │    │转文本)│    │推理)   │    │转语音)│        ││  └──────┘    └──────┘    └────────┘    └──────┘        ││         ↑          ↑           ↑            ↑           ││      Silero    Deepgram   OpenAI/       Cartesia        ││                 /...       Gemini/...    /ElevenLabs    │└──────────────────────────────────────────────────────────┘

核心设计决策

代码结构

livekit-agents/├── livekit/agents/           # 核心框架│   ├── _agent.py            # Agent 基类，定义指令和工具│   ├── _agent_session.py    # AgentSession：会话状态管理│   ├── _agent_server.py     # AgentServer：调度和生命周期│   ├── _job_context.py      # JobContext：会话元数据│   ├── _function_tool.py    # function_tool 装饰器实现│   ├── stt/                 # STT 抽象层│   ├── tts/                 # TTS 抽象层│   ├── llm/                 # LLM 抽象层│   ├── vad/                 # VAD 抽象层│   └── ipc/                 # 进程间通信（调度器-Worker）├── livekit/plugins/         # 官方插件│   ├── openai/              # OpenAI LLM + Realtime API│   ├── deepgram/            # Deepgram STT│   ├── cartesia/            # Cartesia TTS│   ├── silero/              # Silero VAD│   ├── turn_detector/       # 语义话轮检测│   └── elevenlabs/          # ElevenLabs TTS├── examples/                # 丰富的示例代码│   ├── voice_agents/        # 语音 Agent 示例│   ├── other/               # 文本/转录等示例│   └── avatar_agents/       # 视频 Avatar 示例└── tests/                   # 单元测试

部署教程

环境要求

快速上手（5 分钟运行第一个语音 Agent）

第 1 步：安装依赖

# 推荐使用 Python 虚拟环境python3 -m venv venvsource venv/bin/activate# 安装核心框架 + 常用插件pip install "livekit-agents[openai,silero,deepgram,cartesia,turn-detector]"

第 2 步：获取 LiveKit 服务器

# 方案 A：使用 LiveKit Cloud（免费额度足够开发）# 访问 https://cloud.livekit.io 注册，获取 URL、API Key、Secret# 方案 B：自建 LiveKit Serverdocker run -d --name livekit \  -p 7880:7880 -p 7881:7881 -p 7882:7882/udp \  livekit/livekit-server \  --node-ip 127.0.0.1 \  --bind 0.0.0.0

第 3 步：编写你的第一个 Agent

创建文件 weather_agent.py：

from livekit.agents import (    Agent,    AgentServer,    AgentSession,    JobContext,    RunContext,    cli,    function_tool,    inference,)from livekit.plugins import silero@function_toolasync def lookup_weather(context: RunContext, city: str):"""查询指定城市的天气情况"""# 实际项目中可替换为真实天气 APIreturn {"city": city, "weather": "晴", "temperature": "25°C"}server = AgentServer()@server.rtc_session()async def entrypoint(ctx: JobContext):    session = AgentSession(        vad=silero.VAD.load(),  # 本地 VAD，无需 GPU        stt=inference.STT("deepgram/nova-3", language="zh"),        llm=inference.LLM("openai/gpt-4.1-mini"),        tts=inference.TTS("cartesia/sonic-3",                          voice="Chinese Female Voice"),    )    agent = Agent(        instructions="你是一个友好的天气助手，用中文和用户对话。",        tools=[lookup_weather],    )await session.start(agent=agent, room=ctx.room)await session.generate_reply(        instructions="用中文打招呼，询问用户想查询哪个城市的天气"    )if __name__ == "__main__":    cli.run_app(server)

第 4 步：设置环境变量并运行

export LIVEKIT_URL="https://your-project.livekit.cloud"export LIVEKIT_API_KEY="your-api-key"export LIVEKIT_API_SECRET="your-api-secret"export OPENAI_API_KEY="sk-..."export DEEPGRAM_API_KEY="..."export CARTESIA_API_KEY="..."# 开发模式（支持热重载 + 终端测试）python weather_agent.py dev# 终端测试模式（无需 LiveKit 服务器）python weather_agent.py console# 生产模式python weather_agent.py start

低配置适配方案

如果资源有限，可以通过以下方式降低硬件需求：

# 1. 全部使用云端 API，无需 GPUpip install "livekit-agents[openai,deepgram,cartesia]"# 不需要 silero 插件（本地 VAD 需要一定 CPU）# 2. 使用更便宜的模型组合# STT: Deepgram nova-2 (比 nova-3 便宜)# LLM: 使用开源模型通过 OpenAI 兼容 API（如 Ollama）# TTS: 使用 Edge-TTS 免费方案# 3. Docker Compose 一键启动（含 LiveKit Server + Agent）# 创建 docker-compose.ymlcat > docker-compose.yml << 'EOF'version: "3.8"services:  livekit:    image: livekit/livekit-server    ports:      - "7880:7880"      - "7881:7881"      - "7882:7882/udp"command: --node-ip 127.0.0.1 --bind 0.0.0.0  agent:    build: .    environment:      - LIVEKIT_URL=http://livekit:7880      - LIVEKIT_API_KEY=devkey      - LIVEKIT_API_SECRET=secret    depends_on:      - livekitEOF

我的分析

适合谁用

• AI 应用开发者：需要在产品中嵌入语音对话功能（客服、助手、陪练等），要求低延迟和自然交互
• 全栈工程师：希望用 Python 快速搭建从前端（Web/Mobile）到后端的完整语音 Agent 方案
• 创业团队：需要快速验证语音 AI 产品 MVP，LiveKit Cloud 提供免费额度，几乎零成本启动

不适合谁用

• 需要纯离线方案的用户：框架设计偏向云端 API 组合，如果需要在完全离线环境运行，需要自行替换所有 STT/LLM/TTS 为本地模型
• 只需要文本对话的用户：虽然框架支持文本模式，但其核心价值在语音链路，纯文本场景用 LangChain/LlamaIndex 更轻量
• 对成本极度敏感的个人开发者：使用云端 API 组合（STT + LLM + TTS）每分钟调用成本在 0.05-0.3 美元之间，高频使用需关注账单

独立评价

livekit/agents 是我近期看到的语音 AI 框架中 工程化程度最高 的一个。它不是在 Python 里拼凑几个 API 调用，而是从传输协议（WebRTC）、调度架构（AgentServer）、到测试框架（内置 judge 评估）做了完整的系统设计。

项目最值得肯定的设计是将"Agent 应用逻辑"与"基础设施调度"彻底解耦——开发者只需要关注 Agent 类的 instructions 和 tools 定义，而 Worker 生命周期、并发控制、音视频路由全部由框架处理。这种抽象让一个语音 Agent 的开发可以压缩到 50 行代码 以内。

需要指出的是，571 个 open issues 反映出项目仍在快速迭代中，部分插件的文档（尤其是非英语语言的 VAD/TTS 配置）还不够完善。中文语音交互虽然可用，但在 VAD 准确性和 TTS 自然度上仍有优化空间。

GitHub 信号

风险提醒

1. Open Issues 较多：571 个未关闭 Issue 可能意味着问题响应不够及时，生产部署前建议充分测试
2. 依赖外部 API：默认配置需要 Deepgram/Cartesia/OpenAI 等付费 API，成本需自行评估
3. 快速迭代风险：日均多个 commit 说明项目仍在快速演进，API 可能有 breaking change，生产环境建议锁定版本号
4. 中文支持仍在完善：虽然框架支持多语言，但中文 VAD 和 TTS 的最佳实践文档较少

Sources note: 本文项目信息截至发布当日，数据来源 GitHub API。

关注「小陆的AI实战营」，每天一款值得关注的 AI 开源项目，带你从实战角度理解 AI 技术演进。