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
333MB installed
● package 333MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
openai
✓ from livekit.plugins import openai
RealtimeModel
✓ from livekit.plugins.openai.realtime import RealtimeModel
LLM
✓ from livekit.plugins.openai import LLM
✗ from livekit.plugins.openai.llm import LLM
The LLM class is directly exposed under `livekit.plugins.openai` as of recent versions, rather than a submodule.
STT
✓ from livekit.plugins.openai import STT
TTS
✓ from livekit.plugins.openai import TTS
responses.LLM
✓ from livekit.plugins.openai.responses import LLM
Use `openai.responses.LLM` for the newer Responses API, recommended for Python projects when using OpenAI LLMs with provider tools.
This quickstart demonstrates how to initialize a LiveKit AgentSession using the `livekit-plugins-openai` for real-time voice AI. It configures the session to use OpenAI's Realtime API, which integrates speech-to-text (STT), large language model (LLM), and text-to-speech (TTS) for low-latency, multimodal interactions. Ensure your `OPENAI_API_KEY` is set as an environment variable.
import os
from livekit.agents import AgentSession, JobContext
from livekit.plugins import openai
# Set your OpenAI API key as an environment variable or pass it directly.
# os.environ["OPENAI_API_KEY"] = "sk-..."
async def my_agent_entrypoint(ctx: JobContext):
# Ensure OPENAI_API_KEY is set in your environment
openai_api_key = os.environ.get('OPENAI_API_KEY', '')
if not openai_api_key:
print("Error: OPENAI_API_KEY environment variable not set.")
return
# Use the OpenAI Realtime API for a voice AI agent
# The RealtimeModel combines STT, LLM, and TTS for low-latency interactions.
# 'voice' parameter selects the voice for speech generation.
session = AgentSession(
llm=openai.realtime.RealtimeModel(
voice="marin", # Example voice, see OpenAI docs for options
api_key=openai_api_key
)
)
print("LiveKit Agent with OpenAI Realtime API started. Connect a participant to interact.")
# The agent will now handle real-time audio and text interactions
# based on the configured OpenAI RealtimeModel.
# For a full agent loop, you would typically yield control to the LiveKit framework.
# In a real LiveKit Agents application, `my_agent_entrypoint` would be
# registered with the agent server to run for each new session.
# This example demonstrates the core setup for the OpenAI plugin.
Debug
Known issues
breakingLiveKit Agents v1.5.0 introduced 'Adaptive Interruption Handling' which is enabled by default. This feature changes how the agent processes user interruptions (barge-ins vs. back-channels) based on an audio-based ML model, potentially altering previous interruption behaviors based on simpler VAD. While not a breaking API change for `livekit-plugins-openai`, it fundamentally alters agent interaction dynamics within the `livekit-agents` framework.fixReview your agent's conversational flow and adjust if the new interruption handling behavior negatively impacts the user experience. You can configure `turn_detection` options within `RealtimeModel` or other components if needed, though adaptive handling is often preferred for more natural conversations.
affects: livekit-agents >=1.5.0 (which livekit-plugins-openai 1.5.x depends on)
gotchaWhen using `openai.realtime.RealtimeModel` but intending to use a separate Text-to-Speech (TTS) provider (e.g., for custom voices), you *must* explicitly set the `modalities` parameter to `['text']`. Otherwise, the `RealtimeModel` will handle TTS internally, bypassing your custom TTS integration.fixConfigure `modalities=['text']` in your `openai.realtime.RealtimeModel` instance if you're providing a separate TTS engine to the `AgentSession`. Example: `llm=openai.realtime.RealtimeModel(modalities=["text"], api_key=...)`
affects: All versions
gotchaOpenAI API keys or provider-specific keys (e.g., `AZURE_OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `COMETAPI_API_KEY`) are generally required for all plugin usage. If not passed as an argument to the constructor (e.g., `api_key=...`), the plugin attempts to read them from environment variables (e.g., `OPENAI_API_KEY`). Misconfiguration is a common source of errors.fixEnsure the relevant API key is correctly set as an environment variable (e.g., `OPENAI_API_KEY`) or explicitly passed to the constructor of `LLM`, `STT`, `TTS`, or `RealtimeModel` instances.
affects: All versions
gotchaFor OpenAI LLM integrations, LiveKit provides two API modes: the `Responses API` (accessed via `openai.responses.LLM`) and the `Chat Completions API` (accessed via `openai.LLM`). The `Responses API` is recommended for new Python projects due to its support for provider tools (like web search) and newer capabilities, while `Chat Completions API` is for Node.js or legacy Python compatibility. Choosing the wrong one might lead to missing features or unexpected behavior.fixFor new Python projects, prefer `openai.responses.LLM` for OpenAI LLMs to leverage the latest features and provider tools. Use `openai.LLM` for compatibility or Node.js agents.
affects: All versions
gotchaOlder versions (prior to 0.10.9) of `livekit-plugins-openai` for TTS had different default audio output formats. Version 0.10.9 and later standardized on PCM, which might cause incompatibility with some local or third-party TTS services that only support formats like MP3.fixIf experiencing issues with TTS audio format incompatibility, check if your TTS provider supports PCM or if `livekit-plugins-openai` (or the underlying OpenAI API) offers a configuration option for `output_format`. If not, you might need to convert audio formats post-generation or use a different TTS provider.
affects: >=0.10.9
Errors
Common errors & fixes
ImportError: cannot import name 'get_raw_function_info' from 'livekit.agents.llm.tool_context'
This error typically occurs due to an incompatibility between the installed versions of `livekit-agents` and `livekit-plugins-openai`, where `get_raw_function_info` has either moved or been removed in a breaking change.
fixEnsure both `livekit-agents` and `livekit-plugins-openai` are updated to compatible versions, ideally the latest stable releases, or reinstall them together. For example, using `uv` (recommended by LiveKit): `uv add "livekit-agents[openai]"` or `pip install --upgrade livekit-agents livekit-plugins-openai`.
AttributeError: module 'livekit.plugins.openai' has no attribute 'LLMStream'
This error indicates that the `LLMStream` class or function is no longer directly exposed or has been renamed within the `livekit.plugins.openai` module, likely due to an API change or refactoring in a newer version of the library.
fixRefer to the official `livekit-plugins-openai` documentation for the correct way to access LLM streaming capabilities, as the `LLMStream` class may have been integrated differently or replaced by a new API. For direct LLM usage, you typically use `openai.LLM()` and its methods.
openai.APITimeoutError: Request timed out.
This error means that a request to the OpenAI API (or an OpenAI-compatible API) took too long to complete and exceeded the configured timeout limit, often due to network issues, API rate limits, or slow model responses.
fixIncrease the timeout duration if appropriate, optimize your prompts for faster responses, or implement retry logic with exponential backoff. Check your internet connection and verify the API provider's status. For LiveKit agents, timeouts can sometimes be adjusted via configuration options or by ensuring your `livekit-agents` and plugin versions are up-to-date, as older versions might have default short timeouts.
OpenAI Realtime API returned an error: {'type': 'error', 'event_name': 'conversation_already_has_active_response', 'message': 'Conversation already has an active response'}
This specific error from the OpenAI Realtime API occurs when the agent attempts to create a new response (e.g., from an LLM) while another response is still being generated or is active in the same conversation session.
fixImplement proper state management within your agent to ensure only one response is active at a time. This often involves waiting for the current response to complete or be cancelled before initiating a new one. The LiveKit `MultimodalAgent` often handles this, but custom logic or race conditions can expose this error. Check for updates to `livekit-agents` and `livekit-plugins-openai` as these issues can be addressed in newer versions.
AttributeError: 'NotGiven' object has no attribute 'chat'
This error typically arises when a custom `llm_node` method in a LiveKit agent tries to access `self.llm.chat()` before the LLM instance has been fully initialized and bound to the agent session, meaning `self.llm` is still a placeholder `NotGiven` object.
fixEnsure that any custom `llm_node` or similar methods accessing `self.llm.chat()` are only invoked after the `AgentSession` has completed its initialization and the LLM instance is properly assigned. This might involve structuring your agent's lifecycle or adding checks for `self.llm` being a valid LLM object before attempting to use it.
Upgrade
Version history
1.7.1latest on PyPI · released Aug 27, 2026
Audit
Dependencies
livekit-agentsrequiredThis plugin is built on top of the LiveKit Agents framework.
openairequiredRequired for interacting with OpenAI APIs directly (implicitly used by the plugin).