agents-py

LiveKit Agents Python SDK

使用 LiveKit Python Agents SDK 构建语音 AI Agent。

LiveKit MCP 服务工具

此技能可与 LiveKit MCP 服务配合使用，该服务可直接访问最新的 LiveKit 文档、代码示例和变更日志。若需要了解可能在创建此技能后发生变化的最新信息，请使用这些工具。

可用的 MCP 工具：

• docs_search - 搜索 LiveKit 文档站点
• get_pages - 按路径获取特定文档页面
• get_changelog - 获取 LiveKit 软件包的近期版本和更新
• code_search - 搜索 LiveKit 仓库中的代码示例
• get_python_agent_example - 浏览 100 多个 Python Agent 示例

何时使用 MCP 工具：

• 需要最新的 API 文档或功能更新
• 要查找近期示例或代码模式
• 想要确认某项功能是否已在近期版本中添加
• 本地参考资料未涵盖某个特定主题

何时使用本地参考资料：

• 需要快速查阅此技能涵盖的核心概念
• 在离线环境中工作，或希望更快查阅常见模式
• 参考资料中的信息已足以满足需求

结合使用 MCP 工具和本地参考资料，获得最佳体验。

参考资料

按需查阅以下资源：

• ./references/livekit-overview.md -- LiveKit 生态概览，以及这些技能如何协同工作
• ./references/agent-session.md -- AgentSession 生命周期、事件和配置
• ./references/tools.md -- 函数工具、RunContext 和工具结果
• ./references/models.md -- STT、LLM、TTS 模型字符串和插件配置
• ./references/workflows.md -- 多 Agent 移交、Tasks、TaskGroups 和管线节点

安装

uv add "livekit-agents[silero,turn-detector]~=1.3" \
  "livekit-plugins-noise-cancellation~=0.2" \
  "python-dotenv"

环境变量

使用 LiveKit CLI 将凭据载入 .env.local 文件：

lk app env -w

或者手动创建 .env.local 文件：

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

快速开始

使用 STT-LLM-TTS 管线的基本 Agent

from dotenv import load_dotenv
from livekit import agents, rtc
from livekit.agents import AgentSession, Agent, AgentServer, room_io
from livekit.plugins import noise_cancellation, silero
from livekit.plugins.turn_detector.multilingual import MultilingualModel

load_dotenv(".env.local")

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="""You are a helpful voice AI assistant.
            Keep responses concise, 1-3 sentences. No markdown or emojis.""",
        )

server = AgentServer()

@server.rtc_session()
async def entrypoint(ctx: agents.JobContext):
    session = AgentSession(
        stt="assemblyai/universal-streaming:en",
        llm="openai/gpt-4.1-mini",
        tts="cartesia/sonic-3:9626c31c-bec5-4cca-baa8-f8ba9e84c8bc",
        vad=silero.VAD.load(),
        turn_detection=MultilingualModel(),
    )

    await session.start(
        room=ctx.room,
        agent=Assistant(),
        room_options=room_io.RoomOptions(
            audio_input=room_io.AudioInputOptions(
                noise_cancellation=lambda params: noise_cancellation.BVCTelephony()
                    if params.participant.kind == rtc.ParticipantKind.PARTICIPANT_KIND_SIP
                    else noise_cancellation.BVC(),
            ),
        ),
    )

    await session.generate_reply(
        instructions="Greet the user and offer your assistance."
    )

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

使用实时模型的基本 Agent

from dotenv import load_dotenv
from livekit import agents, rtc
from livekit.agents import AgentSession, Agent, AgentServer, room_io
from livekit.plugins import openai, noise_cancellation

load_dotenv(".env.local")

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="You are a helpful voice AI assistant."
        )

server = AgentServer()

@server.rtc_session()
async def entrypoint(ctx: agents.JobContext):
    session = AgentSession(
        llm=openai.realtime.RealtimeModel(voice="coral")
    )

    await session.start(
        room=ctx.room,
        agent=Assistant(),
        room_options=room_io.RoomOptions(
            audio_input=room_io.AudioInputOptions(
                noise_cancellation=lambda params: noise_cancellation.BVCTelephony()
                    if params.participant.kind == rtc.ParticipantKind.PARTICIPANT_KIND_SIP
                    else noise_cancellation.BVC(),
            ),
        ),
    )

    await session.generate_reply(
        instructions="Greet the user and offer your assistance."
    )

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

核心概念

Agent 类

通过继承 Agent 来定义 Agent 行为：

from livekit.agents import Agent, function_tool

class MyAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="Your system prompt here",
        )

    async def on_enter(self) -> None:
        """Called when agent becomes active."""
        await self.session.generate_reply(
            instructions="Greet the user"
        )

    async def on_exit(self) -> None:
        """Called before agent hands off to another agent."""
        pass

    @function_tool()
    async def my_tool(self, param: str) -> str:
        """Tool description for the LLM."""
        return f"Result: {param}"

AgentSession

该会话负责协调语音管线：

session = AgentSession(
    stt="assemblyai/universal-streaming:en",
    llm="openai/gpt-4.1-mini",
    tts="cartesia/sonic-3:voice_id",
    vad=silero.VAD.load(),
    turn_detection=MultilingualModel(),
)

关键方法：

• session.start(room, agent) - 启动会话
• session.say(text) - 直接朗读文本
• session.generate_reply(instructions) - 生成 LLM 响应
• session.interrupt() - 停止当前语音
• session.update_agent(new_agent) - 切换到其他 Agent

函数工具

使用 @function_tool 装饰器：

from livekit.agents import function_tool, RunContext

@function_tool()
async def get_weather(self, context: RunContext, location: str) -> str:
    """Get the current weather for a location."""
    return f"Weather in {location}: Sunny, 72°F"

运行 Agent

# Development mode with auto-reload
uv run agent.py dev

# Console mode (local testing)
uv run agent.py console

# Production mode
uv run agent.py start

# Download required model files
uv run agent.py download-files

LiveKit Inference 模型字符串

使用模型字符串进行简单配置，无需 API 密钥：

STT（语音转文本）：

• "assemblyai/universal-streaming:en" - AssemblyAI 流式识别
• "deepgram/nova-3:en" - Deepgram Nova
• "cartesia/ink" - Cartesia STT

LLM（大语言模型）：

• "openai/gpt-4.1-mini" - GPT-4.1 mini（推荐）
• "openai/gpt-4.1" - GPT-4.1
• "openai/gpt-5" - GPT-5
• "gemini/gemini-3-flash" - Gemini 3 Flash
• "gemini/gemini-2.5-flash" - Gemini 2.5 Flash

TTS（文本转语音）：

• "cartesia/sonic-3:{voice_id}" - Cartesia Sonic 3
• "elevenlabs/eleven_turbo_v2_5:{voice_id}" - ElevenLabs
• "deepgram/aura:{voice}" - Deepgram Aura

最佳实践

1. 始终默认使用 LiveKit Inference 模型字符串来进行语音转文本、LLM 和文本转语音。这样无需管理各个提供商的 API 密钥。只有在确实需要自定义模型、语音克隆、Anthropic Claude 或可自托管模型时，才使用插件。
2. 使用自适应噪声消除，通过 lambda 检测 SIP 参与者，并应用适当的噪声消除（电话通话使用 BVCTelephony，普通参与者使用 BVC）。
3. 使用 MultilingualModel 轮次检测，实现自然的对话流程。
4. 按 Identity、Output rules、Tools、Goals 和 Guardrails 部分组织提示词。
5. 部署到 LiveKit Cloud 前，先在控制台模式下测试。
6. 使用 lk app env -w 将 LiveKit Cloud 凭据加载到环境中。