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-agentsVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.
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.
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.
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`.
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.
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.
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.
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.