livekit/agents

LiveKit Agents – 用于实时 AI 语音代理的 Python 框架

它是什么 – 一个 Python SDK，让您可以构建能够实时聆听、说话甚至观看的服务器端代理。代理本质上是一个运行在 LiveKit 生态系统内，并透过 WebRTC 或电话与用户对话的 LLM 驱动应用程序（例如语音助手）。

核心概念

• Agent – 包装了 LLM、可选工具（函数调用）和一组指令的代码片段。
• AgentSession – 管理单一用户或房间的媒体管道（语音转文字、轮次检测、文字转语音）和对话状态。
• AgentServer – 负责调度会话、启动代理并将它们连接到 LiveKit 房间的进程。
• Plugins – 热门模型提供商（OpenAI、Deepgram、Cartesia、Google 等）的适配器，提供统一的 inference.* API。

主要功能

• 混合搭配任何 STT、LLM 和 TTS 服务。
• 内置作业分发，可同时服务多位用户。
• 完整的 WebRTC 客户端支持（浏览器、移动设备、Unity 等）以及透过 LiveKit 的 SIP 堆栈进行电话集成。
• 轮次检测转换器，用于判断说话者何时结束发言。
• 用于外部工具服务器的一行 MCP 集成。
• 带有“评委”的原生测试框架，用于断言 LLM 行为。
• 开源，可完全运行在自托管的 LiveKit 服务器上。

安装

pip install "livekit-agents[openai,deepgram,cartesia]"

额外的括号会引入最常见模型提供商的可选插件。

快速入门（语音助手）

from livekit.agents import Agent, AgentServer, AgentSession, JobContext, RunContext, cli, function_tool, inference

@function_tool
async def lookup_weather(context: RunContext, location: str):
    return {"weather": "sunny", "temperature": 70}

server = AgentServer()

@server.rtc_session()
async def entrypoint(ctx: JobContext):
    session = AgentSession(
        vad=inference.VAD(),
        stt=inference.STT("deepgram/nova-3", language="multi"),
        llm=inference.LLM("google/gemma-4-31b-it"),
        tts=inference.TTS("cartesia/sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"),
    )
    agent = Agent(instructions="You are a friendly voice assistant.", tools=[lookup_weather])
    await session.start(agent=agent, room=ctx.room)
    await session.generate_reply(instructions="greet the user and ask about their day")

if __name__ == "__main__":
    cli.run_app(server)

设置 LIVEKIT_URL、LIVEKIT_API_KEY 和 LIVEKIT_API_SECRET，以便进程可以加入 LiveKit 房间。

更进阶的模式

• 多代理交接 – 一个代理收集信息，然后将对话交接给专业代理（例如说书人）。交接是通过从工具调用中返回一个新的 Agent 实例来完成的。
• 测试 – SDK 附带一个与 pytest 兼容的测试工具，可以断言给定的用户语句是否触发了预期的函数调用或 LLM 响应。
• MCP 工具 – 连接到 LiveKit Docs MCP 服务器，让代理查询最新的文档或代码搜索。

运行与开发

模式	指令	作用
控制台（快速测试）	python myagent.py console	在本地运行，使用麦克风/音频 I/O，无需服务器
开发	python myagent.py dev	启动带有热重载的 AgentServer；连接到 LiveKit Cloud 或自托管服务器
生产	python myagent.py start	以生产级优化运行

资源

• 完整文档：https://docs.livekit.io/agents/
• 示例仓库：https://github.com/livekit-examples/python-agents-examples
• 社区 Slack、Twitter 和 Discord 链接位于 README 徽章中。

授权 – 框架采用 Apache-2.0；轮次检测模型拥有其专属的 LiveKit 模型授权。

---

LiveKit Agents 让开发者能将任何 LLM 转变为实时语音（或视频）参与者，可从浏览器、移动应用或电话呼叫，并由 LiveKit 的 WebRTC 基础设施提供支持。