正在寻找 JS/TS 库？请查看 AgentsJS。

什么是 Agents？

Agent 框架旨在构建运行在服务器上的实时可编程参与者。利用它，您可以创建能够看、听并理解的多模态对话式语音代理。

特性

• 灵活的集成：全面的生态系统，允许您根据具体用例自由组合合适的 STT、LLM、TTS 和实时 API。
• 集成的任务调度：内置任务调度与分发功能，通过 dispatch APIs 将终端用户连接到代理。
• 丰富的 WebRTC 客户端：使用 LiveKit 的开源 SDK 生态系统构建客户端应用，支持所有主流平台。
• 电话集成：与 LiveKit 的 电话堆栈 无缝协作，使您的代理能够拨打或接听电话。
• 与客户端交换数据：使用 RPCs 和其他 Data APIs 与客户端顺畅地交换数据。
• 语义轮次检测：采用 Transformer 模型检测用户何时结束发言，有助于减少打断。
• MCP 支持：原生支持 MCP。只需一处即可集成 MCP 服务器提供的工具。
• 内置测试框架：编写测试并使用评判器确保您的代理按预期运行。
• 开源：完全开源，允许您在自己的服务器上运行整个堆栈，包括 LiveKit 服务器，这是最常用的 WebRTC 媒体服务器之一。

安装

要安装核心 Agents 库以及常用模型提供商的插件：

pip install "livekit-agents[openai,silero,deepgram,cartesia,turn-detector]~=1.4"

文档与指南

有关该框架及其使用方法的文档，请参阅 这里。

使用 AI 编码代理进行开发

如果您正在使用 AI 编码助手来基于 LiveKit Agents 进行开发，我们建议采用以下设置以获得最佳效果：

1. 安装 LiveKit Docs MCP 服务器 — 为您的编码代理提供最新的 LiveKit 文档、跨 LiveKit 仓库的代码搜索功能以及实用示例。

2. 安装 LiveKit Agent Skill — 为您的编码代理提供构建语音 AI 应用程序的架构指导和最佳实践，包括工作流设计、交接流程、任务分配及测试模式。

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

Agent Skill 与 MCP 服务器配合使用效果最佳：Skill 教导您的代理 如何着手 使用 LiveKit 进行开发，而 MCP 服务器则提供 当前的 API 细节 以便正确实现。

核心概念

• 代理：基于 LLM 的应用程序，具有明确的指令。
• 代理会话：用于管理与终端用户交互的容器。
• 入口点：交互式会话的起点，类似于 Web 服务器中的请求处理器。
• 代理服务器：负责协调任务调度并启动用户会话代理的主要进程。

使用方法

简单的语音代理

---

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


@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=silero.VAD.load(),
        # 可以使用 STT、LLM、TTS 或实时 API 的任意组合
        # 本示例展示了 LiveKit Inference，这是一个通过 LiveKit Cloud 访问不同模型的统一 API
        # 如果需要直接使用模型提供商的密钥，可以替换为以下内容：
        # 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("openai/gpt-4.1-mini"),
        tts=inference.TTS("cartesia/sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"),
    )

    agent = Agent(
        instructions="您是 LiveKit 构建的友好语音助手。",
        tools=[lookup_weather],
    )

    await session.start(agent=agent, room=ctx.room)
    await session.generate_reply(instructions="向用户问好并询问他们今天过得如何")


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

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

• LIVEKIT_URL
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET

多智能体交接

---

这段代码片段已简化。完整示例请参见 multi_agent.py。

...
class IntroAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions=f"你是一名讲故事的人。你的目标是从用户那里收集一些信息，使故事更加个性化和引人入胜。"
            "请询问用户的姓名和来自哪里"
        )

    async def on_enter(self):
        self.session.generate_reply(instructions="向用户问好并收集信息")

    @function_tool
    async def information_gathered(
        self,
        context: RunContext,
        name: str,
        location: str,
    ):
        """当用户提供了使故事个性化和引人入胜所需的信息时调用。

        Args:
            name: 用户的姓名
            location: 用户所在的地方
        """

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

        story_agent = StoryAgent(name, location)
        return story_agent, "让我们开始故事吧！"


class StoryAgent(Agent):
    def __init__(self, name: str, location: str) -> None:
        super().__init__(
            instructions=f"你是一名说书人。利用用户的个人信息使故事更具个性化。"
            f"用户的名字是{name}, 来自{location}"
            # 覆盖默认模型，切换到实时API而非标准LLM
            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=silero.VAD.load(),
        stt="deepgram/nova-3",
        llm="openai/gpt-4.1-mini",
        tts="cartesia/sonic-3:9626c31c-bec5-4cca-baa8-f8ba9e84c8bc",
        userdata=userdata,
    )

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

测试

自动化测试对于构建可靠的智能体至关重要，尤其是在LLM表现出非确定性行为的情况下。LiveKit Agents内置了测试集成，可帮助您创建可靠的智能体。

@pytest.mark.asyncio
async def test_no_availability() -> None:
    llm = google.LLM()
    async AgentSession(llm=llm) as sess:
        await sess.start(MyAgent())
        result = await sess.run(
            user_input="你好，我想下单。"
        )
        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="助手应该询问用户想要什么")
        )

示例

更多示例及详细的设置说明，请参阅 examples目录。如需更多示例，请访问 python-agents-examples 仓库。

🎙️ 入门级智能体 专为语音对话优化的入门级智能体。 代码	🔄 多用户对讲功能 通过按住说话的方式响应房间内的多个用户。 代码
🎵 背景音频 背景环境音和思考音效，以提升真实感。 代码	🛠️ 动态工具创建 动态创建函数工具。 代码
☎️ 外拨呼叫器 能够发起外拨电话的智能体。 代码	📋 结构化输出 使用LLM的结构化输出来指导TTS的语气。 代码
🔌 MCP支持 使用MCP服务器上的工具。 代码	💬 文本专用智能体 完全跳过语音部分，将相同代码用于纯文本集成。 代码
📝 多用户转录器 为房间内所有用户生成转录文本。 代码	🎥 视频化身 可以添加由Tavus、Hedra、Bithuman、LemonSlice等提供的AI化身。 代码
🍽️ 餐厅点餐与预订 一个完整的餐厅接线员智能体示例。 代码	👁️ Gemini Live视觉 一个完整的Gemini Live视觉智能体示例（包括iOS应用）。 代码

运行您的智能体

在终端中测试

python myagent.py console

以终端模式运行您的智能体，支持本地音频输入和输出，便于测试。此模式无需外部服务器或依赖项，非常适合快速验证行为。

使用LiveKit客户端开发

python myagent.py dev

启动智能体服务器，并在文件更改时启用热重载。此模式允许每个进程高效地托管多个并发智能体。

智能体会连接到LiveKit Cloud或您自建的服务器。请设置以下环境变量：

• LIVEKIT_URL
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET

您可以使用任何LiveKit客户端SDK或电话集成进行连接。若想快速上手，不妨试试 Agents Playground。

生产环境运行

python myagent.py start

以生产就绪的优化方式运行智能体。

贡献

Agents框架正处于快速发展阶段，我们欢迎并感谢任何形式的贡献，无论是反馈、错误修复、新功能、新插件和工具，还是更好的文档。您可以在本仓库提交问题、打开PR，或在 LiveKit社区 中与我们交流。

开发环境配置

本项目使用 uv 进行包管理。要安装开发所需的依赖，请运行以下命令：

uv sync --all-extras --dev

示例

本项目在 examples 目录中包含许多示例。要运行这些示例，首先创建 examples/.env 文件，填入 LiveKit 服务器及所需模型提供商的凭据（请参考 examples/.env.example），然后运行：

uv run examples/voice_agents/basic_agent.py dev

更多详细信息，请参阅 示例 README。

测试

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

uv run pytest tests/test_tools.py

每个插件的集成测试需要各种 API 凭据，并且会在 GitHub CI 中自动运行，仅针对由项目维护者提交的 Pull Request。有关详细信息，请查看 测试工作流。

代码格式化

本项目使用 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

LiveKit 生态系统
Agents SDKs	Python · Node.js
LiveKit SDKs	浏览器 · Swift · Android · Flutter · React Native · Rust · Node.js · Python · Unity · Unity (WebGL) · ESP32 · C++
入门应用	Python Agent · TypeScript Agent · React 应用 · SwiftUI 应用 · Android 应用 · Flutter 应用 · React Native 应用 · 网页嵌入
UI 组件	React · Android Compose · SwiftUI · Flutter
服务器 API	Node.js · Golang · Ruby · Java/Kotlin · Python · Rust · PHP（社区版） · .NET（社区版）
资源	文档 · MCP 服务器文档 · CLI 工具 · LiveKit 云服务
LiveKit 服务器开源项目	LiveKit 服务器 · Egress · Ingress · SIP
社区	开发者社区 · Slack 社区 · X 平台 · YouTube 频道

LiveKit Agents 快速上手指南

LiveKit Agents 是一个用于构建实时、可编程语音代理的框架。它支持多模态交互（听、说、理解），可轻松集成各类 STT、LLM 和 TTS 模型，并具备原生的 WebRTC 和电话集成能力。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：Linux、macOS 或 Windows
• Python 版本：3.10 或更高版本
• 依赖项：pip 包管理工具
• LiveKit 账户：需要获取 LIVEKIT_URL、LIVEKIT_API_KEY 和 LIVEKIT_API_SECRET（可在 LiveKit Cloud 免费注册获取，或自建 LiveKit 服务器）

提示：国内开发者若访问 PyPI 较慢，可使用清华或阿里云镜像源加速安装。

安装步骤

使用 pip 安装核心库及常用插件（包含 OpenAI、Silero VAD、Deepgram STT、Cartesia TTS 等）：

pip install "livekit-agents[openai,silero,deepgram,cartesia,turn-detector]~=1.4" -i https://pypi.tuna.tsinghua.edu.cn/simple

如需使用其他模型提供商，可根据需求调整括号内的插件名称。

基本使用

以下是一个最简单的语音代理示例，具备天气查询功能并能主动问候用户。

1. 创建代理文件

新建文件 my_agent.py，填入以下代码：

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


@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=silero.VAD.load(),
        # 使用 LiveKit Inference 统一接口调用模型
        stt=inference.STT("deepgram/nova-3", language="multi"),
        llm=inference.LLM("openai/gpt-4.1-mini"),
        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)

2. 配置环境变量

在终端中设置以下环境变量（替换为你的实际值）：

export LIVEKIT_URL=wss://your-project.livekit.cloud
export LIVEKIT_API_KEY=your_api_key
export LIVEKIT_API_SECRET=your_api_secret

Windows PowerShell 用户使用 $env:LIVEKIT_URL="..." 格式。

3. 运行代理

在终端中启动代理并进行本地测试：

python my_agent.py console

该命令将以控制台模式运行，允许你通过麦克风输入语音并听到代理的语音回复，无需额外部署服务器即可快速验证功能。