# mivi-dev-org/custom-livekit-agents architecture

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

- Interactive diagram: https://gitdiagram.com/mivi-dev-org/custom-livekit-agents
- Repository: https://github.com/mivi-dev-org/custom-livekit-agents

## Overview

LiveKit Agents is a Python framework for server-run, real-time conversational participants. The main path is worker scheduling and dispatching a job, the user entrypoint connecting to a room, and an AgentSession coordinating voice input, agent/LLM and tool behavior, then speech output to the room. Provider plugins supply model integrations; the framework also exposes realtime models, MCP, semantic turn detection, and telemetry. Edges reflect README-described flow and its example; unsampled subsystems are included where documented, without asserting internal calls not shown in the excerpts.

Main entry points: [`livekit-agents/livekit/agents/voice/agent_session.py`](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/voice/agent_session.py) (Agent session), [`livekit-agents/livekit/agents/llm/llm.py`](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/llm.py) (LLM interface), [`livekit-agents/livekit/agents/voice/agent.py`](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/voice/agent.py) (Agent instructions), [`livekit-agents/livekit/agents/job.py`](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/job.py) (Job context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Worker runtime"]
  node_worker["Worker scheduler<br/>[worker.py]"]
  node_job["Job context<br/>[job.py]"]
  node_cli["App CLI<br/>[cli.py]"]
end

subgraph group_conversation["Conversation runtime"]
  node_agent["Agent instructions<br/>[agent.py]"]
  node_session["Agent session<br/>[agent_session.py]"]
  node_roomio["Room audio I/O<br/>[room_io.py]"]
  node_voicegen["Voice generation<br/>[generation.py]"]
  node_vad["Voice activity<br/>[vad.py]"]
end

subgraph group_models["Models and tools"]
  node_stt["Speech recognition<br/>[stt.py]"]
  node_llm["LLM interface<br/>[llm.py]"]
  node_chat["Chat context<br/>[chat_context.py]"]
  node_tools["Function tools<br/>[tool_context.py]"]
  node_realtime["Realtime models<br/>[realtime.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
end

subgraph group_operations["Integrations and observability"]
  node_openai["OpenAI provider<br/>[llm.py]"]
  node_plugins["Provider plugins"]
  node_mcp["MCP integration<br/>[mcp.py]"]
  node_turn["Semantic turn detection<br/>[base.py]"]
  node_telemetry["Metrics and traces"]
end

node_user(("Room participant"))
node_livekit["LiveKit room service"]

node_user -->|"joins room"| node_livekit
node_cli -->|"runs app"| node_worker
node_worker -->|"dispatches job"| node_job
node_job -->|"connects room"| node_livekit
node_job -->|"starts session"| node_session
node_session -->|"runs agent"| node_agent
node_session -.->|"uses room"| node_roomio
node_roomio -.->|"exchanges media"| node_livekit
node_user -.->|"sends voice"| node_roomio
node_session -->|"configures VAD"| node_vad
node_session -->|"configures STT"| node_stt
node_session -->|"configures LLM"| node_llm
node_session -->|"configures TTS"| node_tts
node_agent -->|"generates replies"| node_llm
node_llm -->|"uses context"| node_chat
node_agent -->|"defines tools"| node_tools
node_session -.->|"generates speech"| node_voicegen
node_voicegen -.->|"requests synthesis"| node_tts
node_openai -->|"implements interface"| node_llm
node_plugins -.->|"provides integrations"| node_stt
node_plugins -.->|"provides integrations"| node_tts
node_agent -.->|"uses MCP tools"| node_mcp
node_session -.->|"supports detection"| node_turn
node_llm -->|"emits metrics"| node_telemetry

click node_worker "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/worker.py"
click node_job "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/job.py"
click node_cli "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/cli/cli.py"
click node_agent "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/voice/agent.py"
click node_session "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/voice/agent_session.py"
click node_roomio "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/voice/room_io/room_io.py"
click node_voicegen "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/voice/generation.py"
click node_vad "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/vad.py"
click node_stt "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/stt/stt.py"
click node_llm "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/llm.py"
click node_chat "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/chat_context.py"
click node_tools "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/tool_context.py"
click node_realtime "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/realtime.py"
click node_tts "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/tts/tts.py"
click node_openai "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/llm.py"
click node_plugins "https://github.com/mivi-dev-org/custom-livekit-agents/tree/main/livekit-plugins"
click node_mcp "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/mcp.py"
click node_turn "https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-plugins/livekit-plugins-turn-detector/livekit/plugins/turn_detector/base.py"
click node_telemetry "https://github.com/mivi-dev-org/custom-livekit-agents/tree/main/livekit-agents/livekit/agents/telemetry"

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_worker,node_job,node_cli toneBlue
class node_agent,node_session,node_roomio,node_voicegen,node_vad toneAmber
class node_stt,node_llm,node_chat,node_tools,node_realtime,node_tts toneMint
class node_openai,node_plugins,node_mcp,node_turn,node_telemetry toneRose
class node_user,node_livekit toneIndigo
```

## Components

### Worker runtime

- [Worker scheduler](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/worker.py): `livekit-agents/livekit/agents/worker.py`
- [Job context](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/job.py): `livekit-agents/livekit/agents/job.py`
- [App CLI](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/cli/cli.py): `livekit-agents/livekit/agents/cli/cli.py`

### Conversation runtime

- [Agent instructions](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/voice/agent.py): `livekit-agents/livekit/agents/voice/agent.py`
- [Agent session](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/voice/agent_session.py): `livekit-agents/livekit/agents/voice/agent_session.py`
- [Room audio I/O](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/voice/room_io/room_io.py): `livekit-agents/livekit/agents/voice/room_io/room_io.py`
- [Voice generation](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/voice/generation.py): `livekit-agents/livekit/agents/voice/generation.py`
- [Voice activity](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/vad.py): `livekit-agents/livekit/agents/vad.py`

### Models and tools

- [Speech recognition](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/stt/stt.py): `livekit-agents/livekit/agents/stt/stt.py`
- [LLM interface](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/llm.py): `livekit-agents/livekit/agents/llm/llm.py`
- [Chat context](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/chat_context.py): `livekit-agents/livekit/agents/llm/chat_context.py`
- [Function tools](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/tool_context.py): `livekit-agents/livekit/agents/llm/tool_context.py`
- [Realtime models](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/realtime.py): `livekit-agents/livekit/agents/llm/realtime.py`
- [Speech synthesis](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/tts/tts.py): `livekit-agents/livekit/agents/tts/tts.py`

### Integrations and observability

- [OpenAI provider](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/llm.py): `livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/llm.py`
- [Provider plugins](https://github.com/mivi-dev-org/custom-livekit-agents/tree/main/livekit-plugins): `livekit-plugins`
- [MCP integration](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-agents/livekit/agents/llm/mcp.py): `livekit-agents/livekit/agents/llm/mcp.py`
- [Semantic turn detection](https://github.com/mivi-dev-org/custom-livekit-agents/blob/main/livekit-plugins/livekit-plugins-turn-detector/livekit/plugins/turn_detector/base.py): `livekit-plugins/livekit-plugins-turn-detector/livekit/plugins/turn_detector/base.py`
- [Metrics and traces](https://github.com/mivi-dev-org/custom-livekit-agents/tree/main/livekit-agents/livekit/agents/telemetry): `livekit-agents/livekit/agents/telemetry`

### Other components

- **Room participant**
- **LiveKit room service**

## Connections

- Room participant → LiveKit room service: joins room (evidence: `README.md`)
- App CLI → Worker scheduler: runs app (evidence: `README.md`)
- Worker scheduler → Job context: dispatches job (evidence: `README.md`)
- Job context → LiveKit room service: connects room (evidence: `README.md`)
- Job context → Agent session: starts session (evidence: `README.md`)
- Agent session → Agent instructions: runs agent (evidence: `README.md`)
- Agent session → Room audio I/O: uses room
- Room audio I/O → LiveKit room service: exchanges media
- Room participant → Room audio I/O: sends voice
- Agent session → Voice activity: configures VAD (evidence: `README.md`)
- Agent session → Speech recognition: configures STT (evidence: `README.md`)
- Agent session → LLM interface: configures LLM (evidence: `README.md`)
- Agent session → Speech synthesis: configures TTS (evidence: `README.md`)
- Agent instructions → LLM interface: generates replies (evidence: `README.md`)
- LLM interface → Chat context: uses context (evidence: `livekit-agents/livekit/agents/llm/llm.py`)
- Agent instructions → Function tools: defines tools (evidence: `README.md`)
- Agent session → Voice generation: generates speech
- Voice generation → Speech synthesis: requests synthesis
- OpenAI provider → LLM interface: implements interface (evidence: `livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/llm.py`)
- Provider plugins → Speech recognition: provides integrations
- Provider plugins → Speech synthesis: provides integrations
- Agent instructions → MCP integration: uses MCP tools
- Agent session → Semantic turn detection: supports detection
- LLM interface → Metrics and traces: emits metrics (evidence: `livekit-agents/livekit/agents/llm/llm.py`)
