agents-py

LiveKit Agents Python SDK

LiveKit の Python Agents SDK を使って音声 AI エージェントを構築します。

LiveKit MCP サーバーのツール

このスキルは LiveKit MCP サーバーと連携して動作します。このサーバーでは、最新の LiveKit ドキュメント、コード例、変更履歴に直接アクセスできます。このスキルの作成後に変更された可能性のある最新情報が必要な場合は、これらのツールを使用してください。

利用可能な MCP ツール：

• docs_search - LiveKit ドキュメントサイトを検索します
• get_pages - パスを指定して特定のドキュメントページを取得します
• get_changelog - LiveKit パッケージの最近のリリースと更新を取得します
• code_search - LiveKit リポジトリからコード例を検索します
• get_python_agent_example - 100 件以上の Python エージェントの例を参照します

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 -- マルチエージェントの引き継ぎ、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 パイプラインを使った基本的なエージェント

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)

リアルタイムモデルを使った基本的なエージェント

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 をサブクラス化して、エージェントの動作を定義します。

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) - 別のエージェントに切り替えます

関数ツール

@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"

エージェントの実行

# 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. STT、LLM、TTS には、デフォルトで必ず LiveKit Inference のモデル文字列を使用してください。これにより、プロバイダーごとの API キーを管理する必要がなくなります。カスタムモデル、音声クローン、Anthropic Claude、またはセルフホストモデルが特に必要な場合にのみ、プラグインを使用してください。
2. ラムダを使用した適応型ノイズキャンセリングで SIP 参加者を検出し、適切なノイズキャンセリング（電話通話には BVCTelephony、標準の参加者には BVC）を適用してください。
3. 自然な会話の流れには、MultilingualModel のターン検出を使用してください。
4. プロンプトは、Identity、Output rules、Tools、Goals、Guardrails の各セクションで構成してください。
5. LiveKit Cloud にデプロイする前に、コンソールモードでテストしてください。
6. lk app env -w を使用して、LiveKit Cloud の認証情報を環境に読み込んでください。