LiveKit Azure Plugins

1.5.4 · active · verified Thu Apr 16

livekit-plugins-azure is a Python plugin for the LiveKit Agents framework, providing seamless integration with Azure AI Speech services for Speech-to-Text (STT) and Text-to-Speech (TTS). It is currently at version 1.5.4 and receives frequent updates as part of the broader LiveKit Agents ecosystem.

Common errors

```
azure.core.exceptions.ClientAuthenticationError: Authentication failed.
```
cause The provided Azure Speech Key (AZURE_SPEECH_KEY) is missing, invalid, or expired.

fix Verify that the `AZURE_SPEECH_KEY` environment variable is set correctly and that the key is valid and active in your Azure portal. Also, ensure the key matches the specified region.
```
ValueError: Missing one of: speech_host, (speech_key and speech_region), or (speech_auth_token and speech_region)
```
cause The `azure.STT` or `azure.TTS` constructor did not receive sufficient authentication or endpoint information.

fix Ensure that either `speech_host` is provided, or both `speech_key` and `speech_region` are provided (via environment variables or directly as arguments), or both `speech_auth_token` and `speech_region` are provided.
```
AttributeError: module 'livekit.plugins.azure' has no attribute 'LLM'
```
cause Attempting to instantiate an LLM (or use OpenAI-specific STT/TTS) through the `livekit.plugins.azure` package, which only supports Azure Speech services.

fix For Azure OpenAI services (including LLMs or OpenAI-powered STT/TTS endpoints on Azure), you must import from `livekit.plugins.openai` and use its Azure-specific methods (e.g., `openai.responses.LLM.with_azure()`, `openai.STT.with_azure()`, `openai.TTS.with_azure()`).

Warnings

breaking LiveKit Agents v1.5.0 introduced 'preemptive generation' enabled by default for LLMs and TTS. This can impact latency expectations and resource usage across all agents, including those using Azure plugins. If not desired, it needs to be explicitly disabled during AgentSession initialization.
Fix: To disable preemptive generation, pass `preemptive_generation=False` to your `AgentSession` constructor. `session = AgentSession(ctx, preemptive_generation=False, ...)` [cite: 0 (from prompt)]
gotcha There is a common confusion between `livekit-plugins-azure` and `livekit-plugins-openai`. `livekit-plugins-azure` is for native Azure Speech STT/TTS services. Azure OpenAI (for LLM interactions, or OpenAI-powered STT/TTS endpoints hosted on Azure) requires `livekit-plugins-openai` configured with Azure-specific parameters.
Fix: Use `from livekit.plugins import azure` for Azure Speech STT/TTS. Use `from livekit.plugins import openai` (and methods like `with_azure()`) for Azure OpenAI LLM, STT, or TTS.
gotcha Azure Speech authentication primarily relies on `AZURE_SPEECH_KEY` and `AZURE_SPEECH_REGION` environment variables. While `speech_auth_token` can be used, it's typically ephemeral and must be passed programmatically as an argument, not via environment variables.
Fix: Ensure `AZURE_SPEECH_KEY` and `AZURE_SPEECH_REGION` are correctly set as environment variables or passed directly to the `azure.STT` and `azure.TTS` constructors. If using `speech_auth_token`, it must be supplied explicitly.

Install

pip install livekit-plugins-azure Install LiveKit Azure Plugins

Imports

STT
wrong:
```
from livekit.plugins.azure import STT
```
correct:
```
from livekit.plugins import azure
# ... then use azure.STT(...)
```
The common pattern is to import the 'azure' module, then access STT/TTS via 'azure.STT' or 'azure.TTS'.
TTS
wrong:
```
from livekit.plugins.azure import TTS
```
correct:
```
from livekit.plugins import azure
# ... then use azure.TTS(...)
```
The common pattern is to import the 'azure' module, then access STT/TTS via 'azure.STT' or 'azure.TTS'.

LLM

wrong:

from livekit.plugins import azure
# ... then use azure.LLM()

correct:

from livekit.plugins import openai
# ... then use openai.responses.LLM.with_azure(...)

Azure OpenAI (LLM, and OpenAI-powered STT/TTS) is handled by livekit-plugins-openai, not livekit-plugins-azure.

Quickstart

This quickstart demonstrates how to initialize a LiveKit Agent session using Azure Speech for both Speech-to-Text (STT) and Text-to-Speech (TTS). It requires setting `AZURE_SPEECH_KEY` and `AZURE_SPEECH_REGION` environment variables for authentication.

import os
from livekit.agents import AgentSession, JobContext
from livekit.plugins import azure

async def my_azure_agent(ctx: JobContext):
    # Ensure AZURE_SPEECH_KEY and AZURE_SPEECH_REGION are set in your environment
    # e.g., via a .env file or directly as environment variables.
    speech_key = os.environ.get('AZURE_SPEECH_KEY', '')
    speech_region = os.environ.get('AZURE_SPEECH_REGION', '')

    if not speech_key or not speech_region:
        print("Error: AZURE_SPEECH_KEY and AZURE_SPEECH_REGION environment variables must be set.")
        return

    session = AgentSession(
        ctx,
        stt=azure.STT(
            speech_key=speech_key,
            speech_region=speech_region
        ),
        tts=azure.TTS(
            speech_key=speech_key,
            speech_region=speech_region,
            voice="en-US-JennyNeural" # Specify a voice for TTS
        )
        # You would typically add an LLM (e.g., from livekit.plugins.openai) here
        # llm=openai.responses.LLM.with_azure(...) 
    )

    print("LiveKit Agent session initialized with Azure Speech STT and TTS.")
    # Example: Make the agent say something immediately
    # await session.easy_reply("Hello, I am an AI agent powered by Azure Speech.")
    # This is where your agent's main logic would run
    # await session.run()

view raw JSON →