# karthikrommula/livekit-voice-agent-workshop architecture

> Architecture diagram of the GitHub repository karthikrommula/livekit-voice-agent-workshop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karthikrommula/livekit-voice-agent-workshop
- Repository: https://github.com/karthikrommula/livekit-voice-agent-workshop

## Overview

#### 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`

Main entry points: [`.env.example`](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/.env.example) (LiveKit Cloud), [`agent.py`](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py) (Voice agent), [`pyproject.toml`](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/pyproject.toml) (uv dependencies), [`uv.lock`](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/uv.lock) (Dependency lock)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local runtime"]
  node_deps["uv dependencies<br/>dependency boundary<br/>[pyproject.toml]"]
  node_lockfile["Dependency lock<br/>lockfile<br/>[uv.lock]"]
  node_env_template["Credential template<br/>environment contract<br/>[.env.example]"]
  node_gitignore["Local secret exclusion<br/>source-control boundary<br/>[.gitignore]"]
  node_console["Console I/O<br/>local audio runtime<br/>[agent.py]"]
  node_agent["Voice agent<br/>Python entry point<br/>[agent.py]"]
  node_vad["Voice activity detection<br/>turn detector<br/>[agent.py]"]
end

subgraph group_livekit["LiveKit Cloud"]
  node_stt["Speech-to-text<br/>hosted inference stage<br/>[agent.py]"]
  node_llm["Conversation LLM<br/>hosted inference stage<br/>[agent.py]"]
  node_tts["Text-to-speech<br/>hosted inference stage<br/>[agent.py]"]
  node_cloud{{"LiveKit Cloud<br/>external platform<br/>[.env.example]"}}
end

node_deps -->|"installs runtime"| node_agent
node_lockfile -->|"pins versions"| node_deps
node_env_template -.->|"defines credentials"| node_cloud
node_gitignore -.->|"protects local .env"| node_env_template
node_console -->|"launches"| node_agent
node_console -->|"microphone audio"| node_vad
node_agent -->|"opens session"| node_cloud
node_agent -->|"configures turn-taking"| node_vad
node_vad -->|"speech turn"| node_stt
node_stt -->|"user text"| node_llm
node_llm -->|"response text"| node_tts
node_tts -->|"speaker audio"| node_console
node_cloud -->|"hosts"| node_stt
node_cloud -->|"hosts"| node_llm
node_cloud -->|"hosts"| node_tts

click node_deps "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/pyproject.toml"
click node_lockfile "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/uv.lock"
click node_env_template "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/.env.example"
click node_gitignore "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/.gitignore"
click node_console "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py"
click node_agent "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py"
click node_vad "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py"
click node_stt "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py"
click node_llm "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py"
click node_tts "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py"
click node_cloud "https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/.env.example"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_deps,node_lockfile,node_env_template,node_gitignore,node_console,node_agent,node_vad toneBlue
class node_stt,node_llm,node_tts,node_cloud toneAmber
```

## Components

### Local runtime

Console-based single-user voice session.

- [uv dependencies](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/pyproject.toml): dependency boundary · Python 3.12+ dependencies are resolved and pinned. · `pyproject.toml`
- [Dependency lock](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/uv.lock): lockfile · `uv.lock`
- [Credential template](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/.env.example): environment contract · Documents required LiveKit URL, API key, and secret. · `.env.example`
- [Local secret exclusion](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/.gitignore): source-control boundary · Keeps the real local .env out of source control. · `.gitignore`
- [Console I/O](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py): local audio runtime · Owns laptop microphone input and speaker playback. · `agent.py`
- [Voice agent](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py): Python entry point · Initializes runtime, session, instructions, models, and tools. · `agent.py`
- [Voice activity detection](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py): turn detector · Detects speech boundaries and may download on first run. · `agent.py`

### LiveKit Cloud

Session connectivity and hosted inference.

- [Speech-to-text](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py): hosted inference stage · `agent.py`
- [Conversation LLM](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py): hosted inference stage · Uses conversation context and configured instructions. · `agent.py`
- [Text-to-speech](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/agent.py): hosted inference stage · `agent.py`
- [LiveKit Cloud](https://github.com/karthikrommula/livekit-voice-agent-workshop/blob/main/.env.example): external platform · Provides WebSocket connectivity, credentials, and inference credits. · `.env.example`

## Connections

- uv dependencies → Voice agent: installs runtime
- Dependency lock → uv dependencies: pins versions
- Credential template → LiveKit Cloud: defines credentials
- Local secret exclusion → Credential template: protects local .env
- Console I/O → Voice agent: launches · uv run python agent.py console
- Console I/O → Voice activity detection: microphone audio
- Voice agent → LiveKit Cloud: opens session
- Voice agent → Voice activity detection: configures turn-taking
- Voice activity detection → Speech-to-text: speech turn
- Speech-to-text → Conversation LLM: user text
- Conversation LLM → Text-to-speech: response text
- Text-to-speech → Console I/O: speaker audio
- LiveKit Cloud → Speech-to-text: hosts
- LiveKit Cloud → Conversation LLM: hosts
- LiveKit Cloud → Text-to-speech: hosts