{"id":2570,"library":"livekit-agents","title":"LiveKit Agents","description":"LiveKit Agents is a powerful framework for building realtime voice AI agents that interact over WebRTC. It provides high-level abstractions for managing LiveKit rooms, participants, audio/video streams, and integrating with various AI models (LLMs, STT, TTS) through a flexible plugin architecture. The current version is 1.5.2, with frequent minor releases delivering new features, bug fixes, and updated plugin support.","status":"active","version":"1.5.2","language":"en","source_language":"en","source_url":"https://github.com/livekit/agents","tags":["AI","Realtime","Voice","Agents","LLM","WebRTC","Audio","Video","Framework","Voicebot"],"install":[{"cmd":"pip install livekit-agents","lang":"bash","label":"Install core library"}],"dependencies":[{"reason":"Core LiveKit client library for WebRTC connectivity and room management.","package":"livekit"},{"reason":"Required for using OpenAI's LLM, STT, and TTS services. Other AI providers have their own dedicated plugins (e.g., `livekit-plugins-google`, `livekit-plugins-mistralai`).","package":"livekit-plugins-openai","optional":true}],"imports":[{"symbol":"Agent","correct":"from livekit.agents import Agent"},{"symbol":"JobContext","correct":"from livekit.agents import JobContext"},{"note":"Provides command-line utilities for running and managing agents, including argument parsing and lifecycle management.","symbol":"cli","correct":"from livekit.agents import cli"}],"quickstart":{"code":"import asyncio\nimport os\nfrom livekit.agents import cli, JobContext, Agent\n\nclass EchoAgent(Agent):\n    def __init__(self):\n        super().__init__()\n\n    async def _on_participant_connected(self, ctx: JobContext, participant_sid: str):\n        print(f\"Participant {participant_sid} connected! Listening for chat messages.\")\n        \n        # Access the first speaker node (representing the room or the primary speaker)\n        # and listen for incoming chat messages.\n        async for msg in ctx.initial_speaker_node.chat.iter_messages():\n            print(f\"Received chat message from {msg.participant_identity}: {msg.message}\")\n            # Echo the message back into the room\n            await ctx.initial_speaker_node.chat.send_message(\n                f\"Echo from agent ({ctx.agent_id}): {msg.message}\"\n            )\n\nasync def entrypoint(ctx: JobContext):\n    agent = EchoAgent()\n    agent.on(\"participant_connected\", agent._on_participant_connected)\n    print(f\"Agent {ctx.agent_id} ready in room {ctx.room.name}. Waiting for participants...\")\n\nif __name__ == \"__main__\":\n    # Ensure LiveKit server connection details are available.\n    # For local development, set these as environment variables or pass them directly:\n    # LIVEKIT_URL=\"ws://localhost:7880\" LIVEKIT_API_KEY=\"devkey\" LIVEKIT_API_SECRET=\"secret\"\n    \n    livekit_url = os.environ.get('LIVEKIT_URL', '')\n    livekit_api_key = os.environ.get('LIVEKIT_API_KEY', '')\n    livekit_api_secret = os.environ.get('LIVEKIT_API_SECRET', '')\n\n    if not all([livekit_url, livekit_api_key, livekit_api_secret]):\n        print(\"Error: LiveKit environment variables (LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET) are not set.\")\n        print(\"Please set them or pass them to cli.run_agent.\")\n        exit(1)\n\n    cli.run_agent(\n        entrypoint, \n        agent_name=\"EchoAgent\",\n        livekit_url=livekit_url,\n        livekit_api_key=livekit_api_key,\n        livekit_api_secret=livekit_api_secret\n    )\n","lang":"python","description":"This quickstart demonstrates a basic `EchoAgent` that connects to a LiveKit room. When a participant joins and sends a chat message, the agent echoes the message back into the room. It illustrates the core `Agent` and `JobContext` concepts and how to listen for chat events."},"warnings":[{"fix":"Always review the official changelog for specific breaking changes related to your agent's features or plugins. Thoroughly re-test agent behavior after upgrading, especially if relying on precise timing or specific plugin versions.","message":"Major versions (e.g., 1.5.0) often introduce significant features and internal refactoring. Specifically, 1.5.0 added 'Adaptive Interruption Handling' (enabled by default), and later 1.5.2 updated MistralAI SDK to v2. These changes may subtly alter agent behavior or require code adjustments when using specific plugins.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Install the necessary `livekit-plugins-` package for your desired AI provider (e.g., `pip install livekit-plugins-openai`) if you intend to use specific LLM, STT, or TTS capabilities.","message":"The `livekit-agents` library provides the core framework, but actual AI functionalities (LLM, STT, TTS) are provided by separate `livekit-plugins-*` packages (e.g., `livekit-plugins-openai`). These must be installed independently based on your chosen AI providers.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure these environment variables are correctly set in your deployment environment or pass them directly when invoking `cli.run_agent`. Agents will fail to connect without valid credentials.","message":"All LiveKit Agents require connection details for a LiveKit server. `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` must be correctly configured as environment variables or explicitly passed to `cli.run_agent`.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure your project's Python interpreter is within the specified range. Consider using tools like `pyenv` or virtual environments (`venv`) to manage Python versions effectively.","message":"The library has strict Python version requirements, currently `>=3.10, <3.15`. Using unsupported Python versions (e.g., 3.9 or 3.15+) will lead to installation failures or unexpected runtime errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Always `await` asynchronous calls, avoid CPU-bound or I/O-blocking operations directly in `async` functions. For such tasks, use `asyncio.to_thread()` or dedicated worker processes.","message":"LiveKit Agents is built entirely on `asyncio`. Blocking operations or incorrect `async/await` patterns within your agent logic can lead to performance bottlenecks, unresponsive agents, or deadlocks in the event loop.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}