karthikrommula/livekit-voice-agent-workshop

Purpose and entry point

This is a minimal workshop repository for a real-time cascaded voice agent: microphone speech is transcribed, processed by an LLM, and synthesized back to audio. The sole application entry point is agent.py, launched locally with uv run python agent.py console.

Runtime and dependency boundary

The agent runs on Python 3.12+ with dependencies resolved by uv from pyproject.toml and pinned in uv.lock. Local console mode owns laptop microphone/speaker I/O; it is not a web application.

• pyproject.toml

• uv.lock

• agent.py

Credential and environment boundary

LiveKit project credentials are supplied through environment variables: URL, API key, and API secret. The committed template establishes the required contract, while the real .env remains local and excluded from source control.

• .env.example

• .gitignore

Agent orchestration

agent.py is the control-plane implementation: it initializes the LiveKit agent runtime, configures the conversational instructions/personality, creates the session, and keeps the real-time interaction active until interrupted. It is the intended extension point for changing models, prompts, or adding function tools.

• agent.py

Cascaded inference pipeline

The core data path is streaming audio through three managed inference stages:

1. Speech-to-text converts microphone audio into user text.

2. An LLM produces the response from conversation context and instructions.

3. Text-to-speech renders the response for local speaker playback.

The pipeline uses LiveKit Inference-hosted models rather than direct provider accounts. Default and alternative model IDs are configured in the agent source.

• agent.py

Conversation/session behavior

A voice-activity model detects speech boundaries, enabling turn-taking and triggering the STT → LLM → TTS sequence. The first execution may download this local/runtime model. Console mode is intended for one interactive local session and ends via Ctrl+C.

• agent.py

External infrastructure

LiveKit Cloud provides the WebSocket endpoint, agent/session connectivity, credentials, and hosted STT, LLM, and TTS inference. The required external configuration is obtained from the LiveKit Cloud dashboard; inference usage consumes the project’s free-tier credits.

• .env.example

• agent.py