LiveKit Groq Plugin

1.5.4 · active · verified Thu Apr 16

livekit-plugins-groq is a Python plugin that enables LiveKit Agents to utilize Groq's high-speed inference for Large Language Models (LLM), Speech-to-Text (STT), and Text-to-Speech (TTS). It is actively maintained as part of the livekit-agents ecosystem, with releases generally aligning with the livekit-agents project, currently at version 1.5.4.

Common errors

```
ImportError: cannot import name 'groq' from 'livekit.plugins'
```
cause The `livekit-plugins-groq` package is either not installed, or the Python virtual environment where it's installed is not active.

fix Ensure you have installed the package using `pip install livekit-plugins-groq` and that your virtual environment is activated before running your script.
```
Groq API key not provided. Set GROQ_API_KEY environment variable or pass `api_key` in constructor.
```
cause The Groq API key, essential for authentication, was not found in the environment variables and was not passed directly to the plugin's constructor.

fix Set the `GROQ_API_KEY` environment variable (e.g., in a `.env` file loaded by `python-dotenv`) or provide the key when initializing `groq.LLM(api_key="YOUR_KEY")`, `groq.STT(api_key="YOUR_KEY")`, or `groq.TTS(api_key="YOUR_KEY")`.
```
ValueError: response_format must be one of [flac mp3 mulaw ogg wav]
```
cause When using Groq TTS, an unsupported audio output format was requested, or the default format is no longer valid/supported by the Groq API.

fix Specify a valid `response_format` parameter in your `groq.TTS` configuration, choosing from `flac`, `mp3`, `mulaw`, `ogg`, or `wav`.

Warnings

gotcha The Groq plugin requires an API key for authentication. This key must be provided via the `GROQ_API_KEY` environment variable. Failing to set it will result in authentication errors when attempting to use Groq services.
Fix: Set the `GROQ_API_KEY` environment variable in your system, `.env` file, or pass it directly as `api_key` argument to `groq.LLM`, `groq.STT`, or `groq.TTS`.
breaking Starting with livekit-agents 1.5.0, 'preemptive generation' for LLM and TTS is enabled by default. This feature starts inference before the user's turn fully ends to reduce latency but can lead to increased costs or unexpected behavior if not accounted for.
Fix: If preemptive generation is not desired, it can be disabled during `AgentSession` initialization: `session = AgentSession(preemptive_generation=False, ...)`.
gotcha LiveKit's Groq plugin provides support for specific Groq TTS models (e.g., `playai-tts`). Using deprecated or unsupported model names can lead to errors. An issue was logged in late 2025 regarding deprecated TTS models, which was addressed in subsequent updates.
Fix: Always refer to the latest LiveKit Groq documentation or the Groq API documentation for a current list of supported TTS models. Ensure your `livekit-plugins-groq` version is up-to-date to benefit from fixes.

Install

pip install livekit-plugins-groq Install with pip

Imports

groq
```
from livekit.plugins import groq
```
The Groq plugin exposes LLM, STT, and TTS functionalities through the 'groq' module.
LLM
wrong:
```
from livekit.plugins import groq.LLM
```
correct:
```
from livekit.plugins.groq import LLM
```
Access LLM directly from the groq plugin submodule. It can also be accessed via `groq.LLM` after importing `from livekit.plugins import groq`.

Quickstart

This quickstart demonstrates how to initialize a LiveKit Agent session using Groq as the Large Language Model (LLM) provider. It highlights the essential import and configuration steps, including setting the `GROQ_API_KEY` environment variable. Groq can also be configured for STT and TTS.

import os
from livekit.agents import AgentSession, JobContext, WorkerOptions
from livekit.plugins import groq

# Set your Groq API key (e.g., in a .env file or directly as an environment variable)
os.environ['GROQ_API_KEY'] = os.environ.get('GROQ_API_KEY', 'your_groq_api_key_here')

async def entrypoint(ctx: JobContext):
    session = AgentSession(
        llm=groq.LLM(
            model="llama3-8b-8192", # or 'llama-3.3-70b-versatile'
            temperature=0.7
        ),
        # Optionally add Groq STT and TTS
        # stt=groq.STT(model="whisper-large-v3-turbo"),
        # tts=groq.TTS(model="playai-tts", voice="Arista-PlayAI"),
        # ... other agent session configurations like vad, turn_handling
    )

    # In a real application, you'd handle participant events and process audio/text
    # For a minimal quickstart, this demonstrates LLM initialization.
    # For example:
    # while True:
    #     user_message = await session.stt.recognize_one_utterance()
    #     if user_message:
    #         reply_text = await session.llm.generate_reply(messages=[{'role': 'user', 'content': user_message.text}])
    #         await session.tts.synthesize(reply_text)

    print("Groq LLM initialized within AgentSession. Ensure GROQ_API_KEY is set.")

# Example of how you might run this (typically part of a larger LiveKit Agent server setup)
if __name__ == "__main__":
    # This part is illustrative; actual LiveKit Agent deployment uses AgentServer.start()
    # You would normally run your agent via `python -m your_agent_file dev`
    print("To run a full LiveKit Agent, please refer to the LiveKit Agents documentation.")
    print("Ensure GROQ_API_KEY is set in your environment or .env file.")

view raw JSON →