LiveKit Agents 快速上手5分钟构建你的第一个实时语音AI智能体【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agentsLiveKit Agents 是一个构建实时语音 AI 智能体的 Python 框架让运行在服务器上的智能体能听、能说、能理解。这篇教程带你从克隆仓库到第一次出声只花五分钟再顺路讲清楚会话调度、多智能体交接和自动化测试怎么落地。 它解决了什么问题先看三个你会遇到的场景电话客服用户打进来问我的余额多少智能体要用语音应答还得随时接得住插话会议房间接待有人加入视频房间前台智能体自动打招呼并处理日程预订个性化讲故事先问清用户的姓名和家乡再据此讲一个专属故事。三件事的共性是语音是实时介质会被打断、要秒级响应、还得跨轮次保持上下文。自己搭这套管道意味着要处理音频流、STT/LLM/TTS 串联、打断恢复、WebRTC 接入工作量不小。LiveKit Agents 把这些都做成现成构件你只写智能体的人设指令和工具音频管道、轮次检测、任务调度由框架承担。需要搭建对话式语音助手、电话机器人、语音前台的团队是它最核心的目标用户。五分钟跑通从克隆到出声先拿到代码和依赖git clone https://gitcode.com/GitHub_Trending/agen/agents cd agents pip install livekit-agents[openai,deepgram,cartesia]方括号里的 extras 决定一并安装哪些模型插件按需替换就能换模型栈。跑起来还需要三个环境变量指向你的 LiveKit Cloud 或自建服务器LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET。然后写一个最小智能体 myagent.pyfrom 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( sttinference.STT(deepgram/nova-3, languagemulti), llminference.LLM(openai/gpt-4.1-mini), ttsinference.TTS(cartesia/sonic-3), ) 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)最关键的行是server.rtc_session()它把 entrypoint 标成每会话入口每当有新房间被调度框架就调一次它并注入JobContext里面的ctx.room就是智能体加入的 WebRTC 房间。function_tool会把异步函数自动包成工具docstring 就是 LLM 看到的工具说明——用户问天气时LLM 自己填 location 参数。最后generate_reply让智能体主动开口实现先打招呼的开场。保存后执行python myagent.py console就能直接在终端和它对话。一次会话的完整旅程跑起来之后用户的一句话是怎么变成语音回复的按数据流走一遍任务调度AgentServer。它是主进程负责把终端用户和智能体连起来新房间建立后调度一个任务调用你注册的 entrypoint。worker.py 里能看到它的完整实现。会话容器AgentSession。每段对话的总调度管音频输入、语音识别、回复生成、播放的完整管道还有打断和暂停的处理。定义在 agent_session.py。模型管线STT/LLM/TTS。会话内部三个零件STT 是耳朵把语音变文字LLM 是大脑决定说什么TTS 是嘴巴把文字读出来。仓库里 70 多个模型插件可以任意混搭也可以像示例那样用inference传统一的模型标识。工具调用。LLM 判断需要查天气这类信息时会调用你function_tool装饰的函数执行结果再回到对话流里继续生成回复。Agent 本身只装指令和工具见 agent.py。这个分层的好处是换任何零件都不用动其他部分换 LLM 模型、换 TTS 音色都只是改一行配置。场景实战把智能体真正用起来最小示例只是证明能跑下面这些才是真正要写业务逻辑的地方。让多个角色接力对话痛点收集信息和讲故事是两种职责塞进一个 Agent 会让指令膨胀、模型容易跑偏。LiveKit 的做法是在工具里返回新智能体完成交接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. context.userdata.name name context.userdata.location location return StoryAgent(name, location), Lets start the story!最值得记住三点工具返回值是 Agent 实例时框架自动在当前会话内切换活动智能体并播放衔接话术AgentSession[StoryData]用类型参数声明会话级共享数据context.userdata让前一个角色把姓名和家乡递给后一个角色新智能体构造时可以覆盖模型管线比如交接瞬间从 STTLLMTTS 级联切到端到端的 Realtime API。一行接入MCP工具痛点智能体能力被手写工具限制住了想复用现成的 MCP 服务器又要自己写对接代码。框架原生支持 MCP几乎就是一行session AgentSession( sttinference.STT(deepgram/nova-3), llminference.LLM(openai/gpt-4.1-mini), tools[ mcp.MCPToolset( idmcp_toolset_1, mcp_servermcp.MCPServerHTTP(urlhttp://localhost:8000/sse), ) ], )tools里声明mcp.MCPToolset加一个服务器地址MCP 服务器暴露的工具就全部变成 LLM 可调用工具。完整写法见 examples/voice_agents/mcp/里面还有长耗时工具的超时和进度上报配置。让智能体接电话客服场景不止网页还有电话。LiveKit Agents 可以和电话栈协作让智能体拨打和接听电话。这块细节不多直接看 examples/telephony/bank-ivr/ 里可运行的银行 IVR 示例。从终端到生产三种启动方式怎么选三个命令都是cli.run_app(server)暴露的子命令模式命令适用场景前置条件consolepython myagent.py console终端快速验证本地音频输入输出无需外部服务器需要麦克风/扬声器devpython myagent.py dev配合 LiveKit 客户端 SDK 开发LIVEKIT_URL / API_KEY / API_SECRET 三个环境变量startpython myagent.py start生产环境生产级优化与优雅退出同样三个环境变量为什么 console 不需要外部服务器看 _legacy.py 的_run_console它起一个独立 worker 线程用server.run(devmodeTrue, unregisteredTrue)运行而不向任何 LiveKit 服务器注册再用simulate_job(console-room, ...)伪造一个任务驱动 entrypoint音频挂到终端麦克风/扬声器上——所以配好模型凭据就能开口说话。⚠️ 注意源码中 Python CLI 的console子命令已标注 deprecated官方建议改用 LiveKit CLI 的lk agent consoledev的进程级热重载也移到了 LiveKit CLI 工具链。给智能体做体检自动化测试怎么写传统单测对 LLM 失效同一句话模型这次调工具、下次反问你没法写死assert。LiveKit 的测试框架思路是模拟用户输入驱动完整管线用链式事件断言加裁判模型对付不确定性。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→工具调用的完整管线result.expect做链式断言工具名、工具执行完成这类硬指标直接校验有没有反问用户想点什么这种没法写死的语义正确性交给.judge()让另一个 LLM 裁判评分。想脱离 worker 进程做进程内测试testing.py 里的fake_job_context可以注入一个假任务上下文。 课后练习示例仓库导航练完上面这些推荐去 examples/ 目录挑几个跑通每个都自带 Dockerfile 可以直接容器化basic_agent.py工程化的起步智能体误打断恢复、预生成、AEC 预热这些配置都有实战写法hotel_receptionist/完整酒店前台附十几篇政策文档和评测场景frontdesk/日程前台带场景配置和测试脚本survey/问卷调查智能体配了自动化测试avatar/基于 Tavus、Bithuman、LemonSlice 的数字人视频智能体。更多说明在 examples/README.md。本地开发速查安装开发依赖项目用 uv 管理uv sync --all-extras --dev跑单元测试测试都在tests/目录uv run pytest --unit跑示例先创建examples/.env填入服务器和模型凭据模板是examples/.env.example再uv run examples/voice_agents/basic_agent.py dev格式化与 lint 用 ruffuv run ruff format和uv run ruff check --fix用 pdoc 生成本地文档等低频操作README 里都有现成命令。许可与合规框架本体是 Apache-2.0见 LICENSE轮次检测模型单独采用 LiveKit Model License见 MODEL_LICENSE。两者是分离的如果启用了语义级轮次检测商用前两条许可要分别确认。到这里你已经拿到了完整链路克隆、五分钟出声、理解调度→会话→管线→工具四层结构还学会了交接、MCP 接入和测试。下一步就打开 basic_agent.py把 instructions 改成你负责的业务然后python myagent.py console跑起来聊两句——有卡住的地方多半改改指令和工具描述就能解决。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考