Registry / llm-agents / livekit-agents

livekit-agents

JSON →
library1.7.1pypypi✓ verified 25d ago

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.

pip install livekit-agents
INSTALL
IMPORT
SIG · LIVEKIT-AGENTS
L
livekit-agents
llm-agentspythonv1.7.1
Install
15.5s avg
Import
5090ms
Disk
294MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.1.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 4.360s · 224.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 18.6s · import 4.802s · 359MB
294MB installed
● package 294MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Agent
from livekit.agents import Agent
JobContext
from livekit.agents import JobContext
cli
from livekit.agents import cli
Provides command-line utilities for running and managing agents, including argument parsing and lifecycle management.

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.

import asyncio import os from livekit.agents import cli, JobContext, Agent class EchoAgent(Agent): def __init__(self): super().__init__() async def _on_participant_connected(self, ctx: JobContext, participant_sid: str): print(f"Participant {participant_sid} connected! Listening for chat messages.") # Access the first speaker node (representing the room or the primary speaker) # and listen for incoming chat messages. async for msg in ctx.initial_speaker_node.chat.iter_messages(): print(f"Received chat message from {msg.participant_identity}: {msg.message}") # Echo the message back into the room await ctx.initial_speaker_node.chat.send_message( f"Echo from agent ({ctx.agent_id}): {msg.message}" ) async def entrypoint(ctx: JobContext): agent = EchoAgent() agent.on("participant_connected", agent._on_participant_connected) print(f"Agent {ctx.agent_id} ready in room {ctx.room.name}. Waiting for participants...") if __name__ == "__main__": # Ensure LiveKit server connection details are available. # For local development, set these as environment variables or pass them directly: # LIVEKIT_URL="ws://localhost:7880" LIVEKIT_API_KEY="devkey" LIVEKIT_API_SECRET="secret" livekit_url = os.environ.get('LIVEKIT_URL', '') livekit_api_key = os.environ.get('LIVEKIT_API_KEY', '') livekit_api_secret = os.environ.get('LIVEKIT_API_SECRET', '') if not all([livekit_url, livekit_api_key, livekit_api_secret]): print("Error: LiveKit environment variables (LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET) are not set.") print("Please set them or pass them to cli.run_agent.") exit(1) cli.run_agent( entrypoint, agent_name="EchoAgent", livekit_url=livekit_url, livekit_api_key=livekit_api_key, livekit_api_secret=livekit_api_secret )
Debug
Known issues
breakingMajor 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.
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.
affects: >=1.5.0
gotchaThe `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.
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.
affects: all
gotchaAll 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`.
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.
affects: all
gotchaThe 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.
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.
affects: all
gotchaLiveKit 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.
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.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'livekit.agents.pipeline'
The `livekit.agents.pipeline` module, which previously contained classes like `VoicePipelineAgent`, has been refactored or deprecated in newer versions of the `livekit-agents` library.
fix
Update your code to use the `livekit.agents.AgentSession` class directly, which is the current and recommended approach for building agents. For example, replace `from livekit.agents.pipeline import VoicePipelineAgent` with `from livekit.agents import AgentSession`.
AttributeError: 'Room' object has no attribute 'local_participant'
This error occurs when attempting to access `room.local_participant` directly without ensuring the `Room` object within the agent's context has fully initialized or if the API for accessing the local participant has changed.
fix
Ensure your agent is properly connected to the LiveKit room, and access the local participant through the `AgentSession` object, for example, `session.room.local_participant`. This often means ensuring `await context.connect()` and `await session.start()` have completed before accessing room details.
livekit.agents._exceptions.APIError: no audio frames were pushed for text: [some text]
This specific error, often seen with the ElevenLabs plugin, indicates that the Text-to-Speech (TTS) service processed the text but failed to return any audio frames, usually due to an invalid `voice_id`, unsupported model, or an issue on the ElevenLabs service side.
fix
Verify that the ElevenLabs `voice_id` and `model` configured for your TTS plugin are correct and valid. Check your ElevenLabs account for any quota limits, service disruptions, or other API-related issues.
OpenAI real-time API unresponsive
This issue, often accompanied by `[OpenAI] Realtime API returned an error`, typically points to problems with OpenAI API key validity, selection of an unsupported model for real-time streaming, or exceeding rate limits.
fix
Confirm your OpenAI API key is active and correctly set in your environment. Ensure you are using an OpenAI model compatible with real-time audio (e.g., `gpt-4o-mini`, `gpt-4o`) and check your OpenAI dashboard for any usage or rate limit alerts.
Agent deployment error: 'package @livekit/agents not found'
When deploying a Python agent to LiveKit Cloud, the LiveKit CLI might incorrectly detect your project as a Node.js project if a `package.json` file is present in the same directory, leading to a failure to find Python dependencies.
fix
Remove the `package.json` file from your Python agent's directory before deployment, or explicitly tell the CLI to skip the SDK check by adding the `--skip-sdk-check` flag to your `lk agent create` or `lk agent deploy` command.
Upgrade
Version history
1.7.1latest on PyPI · released Aug 27, 2026
Audit
Dependencies
livekitrequiredCore LiveKit client library for WebRTC connectivity and room management.
livekit-plugins-openaioptionalRequired 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`).
Agent activity
25 hits · last 30 days
node
20
OpenAI (training)
1
Resources
livekit-agents — pip install livekit-agents · libregistry