# livekit-examples/agent-starter-python architecture

> Architecture diagram of the GitHub repository livekit-examples/agent-starter-python, 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/livekit-examples/agent-starter-python
- Repository: https://github.com/livekit-examples/agent-starter-python

## Overview

This repository is a Python LiveKit voice-assistant starter. A user connects through a frontend or telephony client to a LiveKit room; the registered agent handler starts a session, which combines speech recognition, turn handling, an LLM, and speech synthesis. The starter also configures expressive speech, keyterm-aware recognition, and background noise cancellation. README-documented observability is included; implementation details beyond the sampled agent file are not inferred.

Main entry points: [`src/agent.py`](https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py) (Agent session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connection["Connection"]
  node_livekit["LiveKit room"]
  node_handler["Agent handler<br/>[agent.py]"]
end

subgraph group_conversation["Conversation"]
  node_session["Agent session<br/>[agent.py]"]
  node_assistant["Assistant behavior<br/>[agent.py]"]
  node_turns["Turn handling<br/>[agent.py]"]
  node_llm["Language model<br/>[agent.py]"]
  node_observability["Agent observability"]
end

subgraph group_audio["Audio processing"]
  node_stt["Speech recognition<br/>[agent.py]"]
  node_tts["Speech synthesis<br/>[agent.py]"]
  node_cancellation["Noise cancellation<br/>[agent.py]"]
end

node_user(("Voice user"))
node_client["Frontend or phone"]

node_user -->|"speaks to"| node_client
node_client -->|"connects through"| node_livekit
node_livekit -->|"dispatches session"| node_handler
node_handler -->|"starts"| node_session
node_handler -->|"connects room"| node_livekit
node_session -->|"starts with"| node_assistant
node_assistant -->|"configures"| node_llm
node_session -->|"configures"| node_stt
node_session -->|"configures"| node_turns
node_session -->|"configures"| node_tts
node_session -->|"enhances audio"| node_cancellation
node_session -->|"records traces"| node_observability

click node_handler "https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py"
click node_session "https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py"
click node_assistant "https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py"
click node_stt "https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py"
click node_turns "https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py"
click node_llm "https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py"
click node_tts "https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py"
click node_cancellation "https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py"

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_livekit,node_handler,node_user,node_client toneBlue
class node_session,node_assistant,node_turns,node_llm,node_observability toneAmber
class node_stt,node_tts,node_cancellation toneMint
```

## Components

### Connection

- **LiveKit room**
- [Agent handler](https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py): `src/agent.py`

### Conversation

- [Agent session](https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py): `src/agent.py`
- [Assistant behavior](https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py): `src/agent.py`
- [Turn handling](https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py): `src/agent.py`
- [Language model](https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py): `src/agent.py`
- **Agent observability**

### Audio processing

- [Speech recognition](https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py): `src/agent.py`
- [Speech synthesis](https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py): `src/agent.py`
- [Noise cancellation](https://github.com/livekit-examples/agent-starter-python/blob/main/src/agent.py): `src/agent.py`

### Other components

- **Voice user**
- **Frontend or phone**

## Connections

- Voice user → Frontend or phone: speaks to (evidence: `README.md`)
- Frontend or phone → LiveKit room: connects through (evidence: `README.md`)
- LiveKit room → Agent handler: dispatches session (evidence: `src/agent.py`)
- Agent handler → Agent session: starts (evidence: `src/agent.py`)
- Agent handler → LiveKit room: connects room (evidence: `src/agent.py`)
- Agent session → Assistant behavior: starts with (evidence: `src/agent.py`)
- Assistant behavior → Language model: configures (evidence: `src/agent.py`)
- Agent session → Speech recognition: configures (evidence: `src/agent.py`)
- Agent session → Turn handling: configures (evidence: `src/agent.py`)
- Agent session → Speech synthesis: configures (evidence: `src/agent.py`)
- Agent session → Noise cancellation: enhances audio (evidence: `src/agent.py`)
- Agent session → Agent observability: records traces (evidence: `README.md`)
