LiveKit开源语音AI Agent框架：内置MCP支持

想要 JS/TS 库？查看 AgentsJS

Agent Framework 专为构建运行在服务器上的实时、可编程参与者而设计。可用它创建对话式多模态语音 Agent，能够看、听、理解。

灵活的集成：完善的生态系统，可混搭 STT、LLM、TTS 和 Realtime API 以适配各种使用场景。

集成任务调度：内置任务调度与分发功能，提供 dispatch API 将终端用户连接到 Agent。

广泛的 WebRTC 客户端：使用 LiveKit 开源 SDK 生态系统构建客户端应用，支持所有主流平台。

电话集成：与 LiveKit 电话堆栈无缝协作，允许 Agent 拨打或接听来自电话的呼叫。

与客户端交换数据：使用 RPC 及其他 Data API 与客户端无缝交换数据。

语义话轮检测：使用 transformer 模型检测用户何时结束话轮，有助于减少打断。

MCP 支持：原生支持 MCP。用一行代码即可集成 MCP 服务器提供的工具。

内置测试框架：编写测试并使用 judge 确保 Agent 按预期运行。

开源：完全开源，允许在自有服务器上运行完整技术栈，包括 LiveKit Server（最广泛使用的 WebRTC 媒体服务器之一）。

安装核心 Agents 库以及流行模型提供商的插件：

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

框架文档及使用说明见此

使用 AI 编程 Agent 构建

如果使用 AI 编程助手构建 LiveKit Agents，建议按以下方式配置以获得最佳效果：

安装 LiveKit Docs MCP server — 让编程助手访问最新的 LiveKit 文档、LiveKit 仓库的代码搜索以及可运行的示例。

安装 LiveKit Docs MCP server — 让编程助手访问最新的 LiveKit 文档、LiveKit 仓库的代码搜索以及可运行的示例。

安装 LiveKit Agent Skill — 为编程助手提供构建语音 AI 应用的架构指导和最佳实践，包括工作流设计、交接、任务和测试模式。

npx skills add livekit/agent-skills --skill livekit-agents

安装 LiveKit Agent Skill — 为编程助手提供构建语音 AI 应用的架构指导和最佳实践，包括工作流设计、交接、任务和测试模式。

npx skills add livekit/agent-skills --skill livekit-agents

Agent Skill 与 MCP server 配合使用效果最佳：Skill 教 Agent 如何使用 LiveKit 进行构建，而 MCP server 提供实现所需的当前 API 细节。

Agent：基于 LLM 的应用，包含定义的指令。

AgentSession：Agent 的容器，管理与终端用户的交互。

entrypoint：交互式会话的起点，类似于 Web 服务器中的请求处理器。

AgentServer：协调任务调度并为用户会话启动 Agent 的主进程。

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

@function_tool
async def lookup_weather(
    context: RunContext,
    location: str,
):
    """Used to look up weather information."""

    return {"weather": "sunny", "temperature": 70}

server = AgentServer()

@server.rtc_session()
async def entrypoint(ctx: JobContext):
    session = AgentSession(
        vad=inference.VAD(),
        # any combination of STT, LLM, TTS, or realtime API can be used
        # this example shows LiveKit Inference, a unified API to access different models via LiveKit Cloud
        # to use model provider keys directly, replace with the following:
        # from livekit.plugins import deepgram, openai, cartesia
        # stt=deepgram.STT(model="nova-3"),
        # llm=openai.LLM(model="gpt-4.1-mini"),
        # tts=cartesia.TTS(model="sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"),
        stt=inference.STT("deepgram/nova-3", language="multi"),
        llm=inference.LLM("google/gemma-4-31b-it"),  # low-latency gemma, hosted on LiveKit
        tts=inference.TTS("cartesia/sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"),
    )

    agent = Agent(
        instructions="You are a friendly voice assistant built by LiveKit.",
        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)

此示例需要以下环境变量：

此代码片段经过简化。完整示例见 multi_agent.py

...
class IntroAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions=f"You are a story teller. Your goal is to gather a few pieces of information from the user to make the story personalized and engaging."
            "Ask the user for their name and where they are from"
        )

    async def on_enter(self):
        self.session.generate_reply(instructions="greet the user and gather information")

    @function_tool
    async def information_gathered(
        self,
        context: RunContext,
        name: str,
        location: str,
    ):
        """Called when the user has provided the information needed to make the story personalized and engaging.

        Args:
            name: The name of the user
            location: The location of the user
        """

        context.userdata.name = name
        context.userdata.location = location

        story_agent = StoryAgent(name, location)
        return story_agent, "Let's start the story!"

class StoryAgent(Agent):
    def __init__(self, name: str, location: str) -> None:
        super().__init__(
            instructions=f"You are a storyteller. Use the user's information in order to make the story personalized."
            f"The user's name is {name}, from {location}",
            # override the default model, switching to Realtime API from standard LLMs
            llm=openai.realtime.RealtimeModel(voice="echo"),
            chat_ctx=chat_ctx,
        )

    async def on_enter(self):
        self.session.generate_reply()

@server.rtc_session()
async def entrypoint(ctx: JobContext):
    userdata = StoryData()
    session = AgentSession[StoryData](
        vad=inference.VAD(),
        stt="deepgram/nova-3",
        llm="google/gemma-4-31b-it",  # low-latency gemma, hosted on LiveKit
        tts="cartesia/sonic-3:9626c31c-bec5-4cca-baa8-f8ba9e84c8bc",
        userdata=userdata,
    )

    await session.start(
        agent=IntroAgent(),
        room=ctx.room,
    )
...

自动化测试对于构建可靠的 Agent 至关重要，尤其是面对 LLM 的非确定性行为时。LiveKit Agents 原生集成测试功能，帮助你创建可信赖的 Agent。

@pytest.mark.asyncio
async def test_no_availability() -> None:
    llm = google.LLM()
    async with AgentSession(llm=llm) as sess:
        await sess.start(MyAgent())
        result = await sess.run(
            user_input="Hello, I need to place an order."
        )
        result.expect.skip_next_event_if(type="message", role="assistant")
        result.expect.next_event().is_function_call(name="start_order")
        result.expect.next_event().is_function_call_output()
        await (
            result.expect.next_event()
            .is_message(role="assistant")
            .judge(llm, intent="assistant should be asking the user what they would like")
        )

更多示例和详细设置说明见 examples 目录。更多示例见 python-agents-examples 仓库。

针对语音对话优化的入门级 Agent。

🔄 多用户按键说话

通过按键说话响应房间内的多名用户。

背景环境音和思考音频以增强真实感。

🛠️ 动态工具创建

动态创建 function tool。

发起 outbound 电话呼叫的 Agent

使用 LLM 的结构化输出引导 TTS 语气。

使用 MCP 服务器的工具

完全跳过语音，使用相同代码进行纯文本集成

📝 多用户转录员

生成房间内所有用户的转录

添加 AI 虚拟形象，支持 Tavus、Bithuman、LemonSlice 等

🍽️ 餐厅订餐与预约

处理餐厅来电的 Agent 完整示例。

👁️ Gemini Live 视觉

Gemini Live Agent（能看见）的完整示例（包括 iOS 应用）。

python myagent.py console

在终端模式下运行 Agent，启用本地音频输入输出用于测试。此模式不需要外部服务器或依赖项，适合快速验证行为。

使用 LiveKit 客户端开发

python myagent.py dev

启动 Agent server 并启用文件变更热重载。此模式允许每个进程高效托管多个并发 Agent。

Agent 连接到 LiveKit Cloud 或自有服务器。设置以下环境变量：

可以使用任何 LiveKit 客户端 SDK 或电话集成来连接。快速入门可尝试 Agents Playground。

生产环境运行

python myagent.py start

以生产级优化运行 Agent。

Agents 框架采用 Apache-2.0 许可。LiveKit 话轮检测模型采用 LiveKit Model License。

Agents 框架处于活跃开发阶段，所在领域发展迅速。我们欢迎并感谢任何形式的贡献，无论是反馈、bug 修复、功能、新插件和工具，还是更完善的文档。你可以在本仓库提交 issue、开 PR，或在 LiveKit 社区与我们交流。

此项目使用 uv 进行包管理。安装开发依赖：

uv sync --all-extras --dev

此项目在 examples 目录中包含许多示例。运行前，创建文件 examples/.env，填入 LiveKit Server 和任何必要模型提供商的凭证（见 examples/.env.example），然后运行：

uv run examples/voice_agents/basic_agent.py dev

更多信息见 examples README。

单元测试位于 tests 目录，可通过以下方式运行：

uv run pytest --unit

每个插件的集成测试需要各种 API 凭证，并自动在 GitHub CI 中运行（仅限项目维护者提交的 PR）。详见 tests workflow。

此项目使用 ruff 进行格式化和 lint：

uv run ruff format
uv run ruff check --fix

本地生成文档使用 pdoc：

uv sync --all-extras --group docs
uv run --active pdoc --skip-errors --html --output-dir=docs livekit