OpenAI Advanced Voice 框架正式开源

想找 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 server 提供的工具。

内置测试框架：编写测试并使用 judge，确保 Agent 的表现符合预期。

开源：完全开源，可以在自己的服务器上运行整套技术栈，其中包括 LiveKit Server——使用最广泛的 WebRTC 媒体服务器之一。

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

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

你可以在这里找到该框架及其使用方法的文档。

使用 AI coding agent 构建

如果你正在使用 AI coding assistant 开发 LiveKit Agents，建议采用以下配置，以获得最佳效果：

安装 LiveKit Docs MCP server——让 coding agent 能够访问最新的 LiveKit 文档、跨 LiveKit 代码仓库进行代码搜索，以及获取可运行的示例。

安装 LiveKit Docs MCP server——让 coding agent 能够访问最新的 LiveKit 文档、跨 LiveKit 代码仓库进行代码搜索，以及获取可运行的示例。

安装 LiveKit Agent Skill——为 coding agent 提供构建语音 AI 应用所需的架构指导和最佳实践，包括工作流设计、handoff、任务及测试模式。npx skills add livekit/agent-skills --skill livekit-agents

安装 LiveKit Agent Skill——为 coding agent 提供构建语音 AI 应用所需的架构指导和最佳实践，包括工作流设计、handoff、任务及测试模式。

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

Agent Skill 与 MCP server 配合使用时效果最佳：Skill 会教 Agent 应该如何使用 LiveKit 进行构建，而 MCP server 则提供当前最新的 API 细节，帮助它正确完成实现。

Agent：具有明确 instructions 的 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。

用于拨打外呼电话的 Agent。

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

使用 MCP server 提供的工具。

完全跳过语音，使用同一套代码实现纯文本集成。

📝 多用户转录器

为房间内的所有用户生成转录文本。

使用 Tavus、Bithuman、LemonSlice 等服务添加 AI avatar。

🍽️ 餐厅点餐与预订

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

👁️ Gemini Live 视觉

一个能够看见的 Gemini Live Agent 完整示例，其中包括 iOS 应用。

python myagent.py console

以终端模式运行 Agent，支持使用本地音频输入和输出进行测试。该模式不需要外部服务器或依赖项，适合快速验证 Agent 行为。

使用 LiveKit 客户端进行开发

python myagent.py dev

启动 Agent Server，并在文件发生变化时启用热重载。在这种模式下，每个进程都可以高效承载多个并发 Agent。

Agent 会连接到 LiveKit Cloud 或你自行托管的服务器。请配置以下环境变量：

你可以使用任意 LiveKit client SDK 或电话集成进行连接。如需快速开始，可以尝试 Agents Playground。

在生产环境中运行

python myagent.py start

使用面向生产环境的优化来运行 Agent。

Agents framework 采用 Apache-2.0 许可证。LiveKit 的轮次检测模型采用 LiveKit Model License。

Agents framework 正处于活跃开发阶段，而它所在的领域也在飞速演进。我们欢迎并感谢任何形式的贡献，无论是反馈、bug 修复、新功能、新插件与工具，还是更完善的文档。你可以在本代码仓库中提交 issue、发起 PR，或前往 LiveKit 社区与我们交流。

本项目使用 uv 管理 package。安装开发依赖：

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 凭据。对于项目维护者提交的 PR，这些测试会在 GitHub CI 中自动运行。详情请参阅 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