LiveKit Agents 框架实战指南：构建、运行与测试实时语音 AI 智能体-北京尧图网络

LiveKit Agents 框架实战指南构建、运行与测试实时语音 AI 智能体【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agentsLiveKit Agents 是一个用于构建实时可编程参与者的 Python 框架目标是让开发者在服务器上运行可听、可见、可理解的多模态语音智能体。本文以仓库根目录 README.md 为主线完整覆盖框架的核心概念、最小可用示例、多智能体交接与内置测试框架并结合 livekit-agents/livekit/agents/cli/cli.py、livekit-agents/livekit/agents/worker.py 等源码剖析console/dev/start三种运行模式背后的实现机制帮助读者掌握从本地终端验证到生产部署的完整链路。框架定位与核心特性Agent Framework 的设计目标是构建运行在服务器上的实时、可编程参与者realtime, programmable participants用它创建对话式、多模态的语音智能体。README 中列出的特性可以归纳为五个方面灵活集成一套可以任意混搭 STT语音识别、LLM大语言模型、TTS语音合成与 Realtime API 的插件生态按业务场景自由组合内置任务调度集成任务调度与分发机制dispatch APIs负责把终端用户与智能体连接起来广覆盖的 WebRTC 客户端客户端应用可使用 LiveKit 开源 SDK 生态构建支持各主流平台电话集成与 LiveKit 的 telephony 栈无缝协作智能体可以拨打或接听电话与客户端交换数据通过 RPC 与 Data API 在智能体和客户端之间交换结构化数据语义级轮次检测使用 transformer 模型判断用户是否说完当前一句话end-of-turn从而减少误打断MCP 原生支持一行代码即可接入 MCP 服务器提供的工具内置测试框架编写测试并使用 judge评审模型来验证智能体的行为是否符合预期全栈开源整条技术栈包括 LiveKit WebRTC 媒体服务器都可以部署在自己的服务器上。仓库结构也印证了这种核心库插件生态的布局核心框架位于 livekit-agents/livekit/agents/ 目录包含voice、llm、stt、tts、cli、inference等子包而 70 余个模型服务商插件全部集中在 livekit-plugins/ 目录下如livekit-plugins-openai、livekit-plugins-deepgram、livekit-plugins-cartesia、livekit-plugins-turn-detector等。安装方式安装核心 Agents 库以及常用模型服务商插件只需一条命令pip install livekit-agents[openai,deepgram,cartesia]其中方括号中的 extras 决定要一并安装的模型插件按需替换或增加 extras 即可切换模型栈。此外README 还推荐了一个面向 AI 编码助手的配套做法为编码 Agent 安装 LiveKit 官方文档 MCP 服务器与 Agent Skill让 AI 在生成代码时能获取最新的 API 细节与架构最佳实践——前者提供当前 API 文档后者提供如何构建语音应用的方法论指导。核心概念README 定义了框架的四个基本构件它们在源码中都有明确对应概念含义源码位置Agent一个带有明确指令instructions的 LLM 应用livekit-agents/livekit/agents/voice/agent.pyAgentSession智能体的容器管理与终端用户的交互音频输入、语音识别、生成、播放的完整管道livekit-agents/livekit/agents/voice/agent_session.pyentrypoint交互式会话的入口函数类似 Web 服务器中的请求处理器通过server.rtc_session()装饰器注册AgentServer主进程负责任务调度job scheduling并为各用户会话拉起智能体livekit-agents/livekit/agents/worker.py从 livekit-agents/livekit/agents/init.py 的导出清单可以确认这些概念的一等公民地位包顶层直接导出AgentServer、WorkerOptions、JobContext、JobRequest、Agent、AgentSession、function_tool、ChatContext、RunContext、RunResult等符号mcp模块则通过__getattr__懒加载以避免强依赖。也就是说编写一个智能体所需的服务端调度worker/job 会话容器voice 工具系统llm.tool_context三块拼图都在根包中开箱即用。实战一最简语音智能体下面这个完整可运行的示例继承了 README 的Simple voice 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( vadinference.VAD(), # 任意组合 STT、LLM、TTS 或 Realtime API 都可以。 # 这里使用 LiveKit Inference——通过 LiveKit Cloud 访问不同模型的统一 API # 如果想直接用模型服务商的 key可替换为 # from livekit.plugins import deepgram, openai, cartesia # sttdeepgram.STT(modelnova-3), # llmopenai.LLM(modelgpt-4.1-mini), # ttscartesia.TTS(modelsonic-3, voice9626c31c-bec5-4cca-baa8-f8ba9e84c8bc), sttinference.STT(deepgram/nova-3, languagemulti), llminference.LLM(google/gemma-4-31b-it), # LiveKit 托管的低延迟 gemma ttsinference.TTS(cartesia/sonic-3, voice9626c31c-bec5-4cca-baa8-f8ba9e84c8bc), ) agent Agent( instructionsYou are a friendly voice assistant built by LiveKit., tools[lookup_weather], ) await session.start(agentagent, roomctx.room) await session.generate_reply(instructionsgreet the user and ask about their day) if __name__ __main__: cli.run_app(server)运行前提——环境变量。该示例需要以下三个环境变量指向 LiveKit Cloud 或自建 LiveKit 服务器LIVEKIT_URLLIVEKIT_API_KEYLIVEKIT_API_SECRET代码要点解读function_tool装饰的异步函数会被自动包装为工具FunctionTool其 docstring 成为 LLM 可见的工具说明类型标注的参数成为 LLM 填充的入参context: RunContext参数是框架注入的运行期上下文可访问会话状态与共享数据server.rtc_session()装饰的entrypoint是每会话入口每当有新的房间任务被调度AgentServer就会为它调用该协程并注入JobContext其中ctx.room是智能体加入的 WebRTC 房间AgentSession构造参数即模型管线vad静音/活动检测、stt、llm、tts可任意混搭也可以传字符串模型标识如deepgram/nova-3由框架自动实例化session.start(agent..., room...)把智能体挂入会话并绑定房间随后session.generate_reply(instructions...)主动发起第一轮回复实现智能体先打招呼的开场白模式。仓库中更完整的参考实现是 examples/voice_agents/basic_agent.py它在最简骨架之上演示了工程化配置turn_handlingTurnHandlingOptions(...)中的resume_false_interruption检测到误打断后自动恢复播放与preemptive_generation在等待用户说完的同时让 LLM 预先生成回复以降低首字延迟、aec_warmup_duration开播初期屏蔽打断留给客户端回声消除校准、tts_text_transforms过滤 emoji/markdown、替换特定发音以及stt_context_options的关键词检测LLM 自动把高频术语注入 STT 上下文提高专有名词识别率。这些配置项正是 README 中语义轮次检测减少打断特性的具体落点。实战二多智能体交接Handoff当一次会话需要多个角色分工例如信息收集员收集用户姓名和籍贯故事讲述员负责讲故事时LiveKit Agents 支持在工具调用中直接返回新智能体来完成交接。下面是 README 的节选片段完整示例请查阅官方文档... class IntroAgent(Agent): def __init__(self) - None: super().__init__( instructionsfYou 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(instructionsgreet 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, Lets start the story! class StoryAgent(Agent): def __init__(self, name: str, location: str) - None: super().__init__( instructionsfYou are a storyteller. Use the users information in order to make the story personalized. fThe users name is {name}, from {location}, # 覆盖默认模型从标准 LLM 切换到 Realtime API llmopenai.realtime.RealtimeModel(voiceecho), chat_ctxchat_ctx, ) async def on_enter(self): self.session.generate_reply() server.rtc_session() async def entrypoint(ctx: JobContext): userdata StoryData() session AgentSessionStoryData, sttdeepgram/nova-3, llmgoogle/gemma-4-31b-it, # LiveKit 托管的低延迟 gemma ttscartesia/sonic-3:9626c31c-bec5-4cca-baa8-f8ba9e84c8bc, userdatauserdata, ) await session.start( agentIntroAgent(), roomctx.room, ) ...这个片段揭示了交接模式的三个关键机制工具即跳转information_gathered返回(story_agent, Lets start the story!)元组——框架检测到工具返回值是Agent实例后会在当前会话内切换活动智能体并播放返回的衔接话术userdata 跨智能体共享AgentSession[StoryData]通过类型参数声明会话级共享数据context.userdata让前一个智能体把收集到的name/location传递给后继智能体实现状态延续每智能体模型覆盖StoryAgent构造时传入llmopenai.realtime.RealtimeModel(voiceecho)在交接的同时把模型管线从STTLLMTTS 级联切换为端到端的 Realtime API并显式携带chat_ctx保留对话历史。实战三内置测试框架LLM 的行为具有非确定性自动化测试是构建可靠智能体的必选项。README 展示了原生测试集成pytest.mark.asyncio async def test_no_availability() - None: llm google.LLM() async with AgentSession(llmllm) as sess: await sess.start(MyAgent()) result await sess.run( user_inputHello, I need to place an order. ) result.expect.skip_next_event_if(typemessage, roleassistant) result.expect.next_event().is_function_call(namestart_order) result.expect.next_event().is_function_call_output() await ( result.expect.next_event() .is_message(roleassistant) .judge(llm, intentassistant should be asking the user what they would like) )断言链路解读sess.run(user_input...)模拟一次用户输入并驱动完整管线识别→LLM→工具调用→合成返回RunResultresult.expect提供链式事件断言——is_function_call(namestart_order)校验工具名、is_function_call_output()校验工具执行完成、is_message(roleassistant)校验助手回复存在而.judge(llm, intent...)则把助手是否询问了用户想点什么这类无法硬编码判断的语义正确性交给另一个 LLM 做裁判式评分。skip_next_event_if还处理了模型可能先输出空消息这类不确定性分支。这套测试基础设施在源码中有清晰映射断言原语定义于 livekit-agents/livekit/agents/voice/run_result.pyRunResult、RunAssert、EventAssert等并在 livekit-agents/livekit/agents/init.py 顶层导出若需要脱离AgentServer/worker 进程做进程内测试框架提供了 livekit-agents/livekit/agents/testing.py 中的fake_job_context上下文管理器——它注入一个fake_job的JobContext使get_job_context()及其访问点行为与真实任务一致可以配合真实房间直接session.start(...)仓库自身的 tests/ 目录包含数百个测试文件如test_agent_session.py、test_tool_proxy.py、test_llm_fallback.py既是测试框架用法的示范也覆盖了打断恢复test_false_interruption_resume.py、预生成死锁test_preemptive_pause_deadlock.py等语音交互中的疑难路径。示例项目导航README 的 Examples 一节链接了仓库内若干可直接运行的示例均在 examples/ 目录下示例说明路径Starter Agent面向语音对话优化的起步智能体examples/voice_agents/basic_agent.pyMCP support使用 MCP 服务器提供的工具examples/voice_agents/mcp/Multi-user transcriber输出房间内所有用户的转写文本examples/other/transcription/multi-user-transcriber.pyVideo avatars基于 Tavus、Bithuman、LemonSlice 等的数字人视频智能体examples/avatar/除上述四个外examples/目录还包括frontdesk日程前台、healthcare医疗预约、hotel_receptionist酒店前台含策略文档与评测场景、survey问卷调查、telephony电话 IVR、primitives回声等最底层原语等成套示例每个带Dockerfile的示例均可容器化部署。更多示例的说明见 examples/README.md。运行你的智能体console / dev / start 三种模式README 将运行方式分为三档全部通过cli.run_app(server)暴露的子命令驱动1. 终端调试python myagent.py console在终端模式运行智能体启用本地音频输入/输出。该模式不依赖外部服务器适合快速验证行为。2. 配合 LiveKit 客户端开发python myagent.py dev启动 Agent 服务器并允许连接 LiveKit Cloud 或自建服务器需设置LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET三个环境变量任何 LiveKit 客户端 SDK 或电话集成都可作为对端接入。3. 生产运行python myagent.py start以生产级优化运行智能体。源码级机制剖析这三个子命令由 livekit-agents/livekit/agents/cli/_legacy.py 中的 typer 应用构建console命令定义于约 L1652、start于约 L1710、dev于约 L1769要点如下凭据解析start与dev的--url/--api-key/--api-secret选项均声明了envvarLIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET因此命令行参数与环境变量等价环境变量即可满足 README 的前提要求--log-level同理支持LIVEKIT_LOG_LEVELconsole 模式的实现_run_console会启动一个独立的_ConsoleWorker线程在独立事件循环中调用server.run(devmodeTrue, unregisteredTrue)并不向服务器注册unregisteredTrue然后通过server.simulate_job(console-room, agent_identityconsole, fake_jobTrue)伪造一个任务来驱动 entrypoint——这正是不依赖外部服务器的原因控制台音频通过AgentsConsole的acquire_io挂接TcpAudioInput/TcpAudioOutput支持音频/文本两种模式切换与--record会话录制dev/start 的 worker 路径二者都走 livekit-agents/livekit/agents/cli/cli.py 中的_run_worker。该函数先按 CLI 参数server.update_options(ws_url..., api_key..., api_secret...)随后调用server.run(devmode...)dev 模式传devmodeTrue并注册了相当完备的优雅退出机制首次 SIGINT/SIGTERM 仅调度退出并在非 dev 模式下执行server.drain()等待在途任务结束start命令还提供--drain-timeout配置等待时长3 秒看门狗_EXIT_ESCALATION_TIMEOUT 3.0在事件循环被同步代码阻塞时升级为强制中断二次 CtrlC 则os._exit(1)强制退出——这些细节保证了生产环境下start模式收到停止信号时不会粗暴截断正在进行的语音会话。需要注意的版本现状从源码注释与运行时提示看Python 侧的console子命令已标注 deprecated建议改用 LiveKit CLI 的lk agent consoledev的进程内自动热重载hot-reload也已从 Python CLI 中移除热重载能力转移到了lk agent dev。README 中dev 模式支持热重载的描述对应的是 LiveKit CLI 工具链的整体能力在 Python CLI 内直接跑dev时该能力不可用这一点在选型测试手段时应予注意。本地开发依赖、测试与代码规范README 的 Contributing 章节给出了仓库自身的开发约定同样适用于基于该仓库二次开发的团队依赖管理uv。项目使用 uv 做包管理安装开发依赖uv sync --all-extras --dev运行示例。在examples/下创建examples/.env文件写入 LiveKit Server 与各模型服务商的凭据模板见 examples/.env.example然后运行uv run examples/voice_agents/basic_agent.py dev单元测试。测试位于 tests/ 目录uv run pytest --unit各插件的集成测试需要相应 API 凭据会在项目维护者提交的 PR 上由 CI 自动运行详见 .github/workflows/tests.yml。格式化与 Lint。项目使用 ruffuv run ruff format uv run ruff check --fixAPI 文档生成。使用 pdoc 本地生成文档uv sync --all-extras --group docs uv run --active pdoc --skip-errors --html --output-dirdocs livekit许可证Agents 框架采用 Apache-2.0 许可证见 LICENSELiveKit 的轮次检测turn detection模型则单独采用 LiveKit Model License见 MODEL_LICENSE。如果你的应用启用了语义级轮次检测模型侧的许可条款与框架本体是分离的商用前需分别确认。小结LiveKit Agents 把实时语音智能体拆解为四层可独立替换的构件AgentServer负责进程与任务调度AgentSession负责交互管道与音频 I/OAgent负责指令、工具与生命周期钩子STT/LLM/TTS/Realtime 模型则作为可插拔零件按需组合。配合console无服务器验证、dev/start两种部署形态、以及RunResult.expect judge 的测试体系开发者可以在同一套代码上完成从终端冒烟测试到生产调度的全过程源码livekit-agents/livekit/agents/与示例examples/中提供了每一层机制的完整实现参考。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

LiveKit Agents 框架实战指南：构建、运行与测试实时语音 AI 智能体

相关推荐

商丘做建设网站的公司3个最佳实践解决网站被黑

数据库技术演进：从关系型到AI原生的关键突破

事件溯源实战：解决微服务数据一致性与业务逻辑难题

更多资讯

Flutter与OpenHarmony跨平台开发实战指南

ms-swift GRPO 训练实战指南：算法原理、Colocate/Async 双模式部署与参数详解

Envoy 降级端点（Degraded Endpoints）：负载溢出机制与 detect_degraded_hosts 源码解析