For AI agents: a documentation index is available at /llms.txt. Markdown versions of all pages can be requested by appending `.md` to the URL, or by setting the `Accept` header to `text/markdown`.
Skip to main content
Integrations and SDKsLiveKit

LiveKit quickstart

Build a voice AI agent with Speechmatics Speech to Text and Text to Speech using LiveKit Agents.

Build a real-time voice agent with Speechmatics and LiveKit in minutes.

LiveKit Agents is a framework for building voice AI applications using WebRTC. Plug Speechmatics STT and TTS into your voice agent pipeline. The STT plugin uses agent STT, our turn-based transcription for voice agents, powered by Linden 1.

Linden 1 requires LiveKit Agents v1.8.2 or later.

Features​

  • Real-time transcription — low-latency segments as users speak
  • Speaker diarization — identify and track multiple speakers
  • Turn detection — a VAD in your agent, or Speechmatics server-side
  • Natural TTS voices — choose from multiple voice options
  • Noise robustness — accurate recognition in challenging audio environments
  • Global language support — works with diverse accents and dialects

Prerequisites​

Setup​

This guide assumes LiveKit Cloud. If you want to self-host LiveKit instead, follow LiveKit's self-hosting guide and configure LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET for your deployment: https://docs.livekit.io/transport/self-hosting/

1. Create project​

mkdir voice-agent && cd voice-agent

2. Install dependencies​

uv init
uv add "livekit-agents[speechmatics,openai,silero]~=1.8.2" python-dotenv

The silero extra supplies the VAD that closes each turn. See Turn detection modes.

3. Install and authenticate the LiveKit CLI​

Install the LiveKit CLI. For additional installation options, see the LiveKit CLI setup guide: https://docs.livekit.io/home/cli/cli-setup/

macOS:

brew install livekit-cli

Linux:

curl -sSL https://get.livekit.io/cli | bash

Windows:

winget install LiveKit.LiveKitCLI

Authenticate and link your LiveKit Cloud project:

lk cloud auth

4. Configure environment​

Run the LiveKit CLI to write your LiveKit Cloud credentials to a .env.local file:

lk app env -w

This creates a .env.local file with your LiveKit credentials. Add your Speechmatics and OpenAI keys:

.env.local
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=...
LIVEKIT_API_SECRET=...
SPEECHMATICS_API_KEY=your_speechmatics_key
OPENAI_API_KEY=your_openai_key

5. Create your agent​

Create a main.py file:

main.py
from dotenv import load_dotenv
from livekit import agents
from livekit.agents import AgentSession, Agent, RoomInputOptions
from livekit.plugins import openai, silero, speechmatics

load_dotenv(".env.local")


class VoiceAssistant(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful voice assistant. Be concise and friendly."
        )


async def entrypoint(ctx: agents.JobContext):
    await ctx.connect()

    # Voice Activity Detection: Silero, shared with the STT plugin below
    vad = silero.VAD.load()

    # Speech to Text: Speechmatics agent STT. The VAD closes each turn.
    stt = speechmatics.STT(vad=vad)

    # Language Model: OpenAI
    llm = openai.LLM(model="gpt-4o-mini")

    # Text to Speech: Speechmatics
    tts = speechmatics.TTS()

    # Create and start session
    session = AgentSession(
        stt=stt,
        llm=llm,
        tts=tts,
        vad=vad,
    )

    await session.start(
        room=ctx.room,
        agent=VoiceAssistant(),
        room_input_options=RoomInputOptions(),
    )

    await session.generate_reply(
        instructions="Say a short hello and ask how you can help."
    )


if __name__ == "__main__":
    agents.cli.run_app(
        agents.WorkerOptions(entrypoint_fnc=entrypoint),
    )

Both plugins run on their defaults here. See Speech to text to configure diarization, turn detection and language, and Text to speech to choose a voice.

6. Run your agent​

Run your agent in dev mode to connect it to LiveKit and make it available from anywhere on the internet:

python main.py dev

Open the LiveKit Agents Playground to test your agent.

Run your agent in console mode to speak to it locally in your terminal:

python main.py console

Next steps​