### Complete Agent Session Example

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/agent-session.md

This example demonstrates a full agent session setup, including loading VAD, configuring STT and TTS, and starting the session with audio enhancement.

```python
@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    ctx.log_context_fields = {"room": ctx.room.name}
    
    # Load VAD from prewarmed userdata
    vad = ctx.proc.userdata["vad"]
    
    # Create pipeline
    session = AgentSession(
        stt=inference.STT(model="deepgram/nova-3", language="multi"),
        tts=inference.TTS(
            model="cartesia/sonic-3",
            voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"
        ),
        turn_detection=MultilingualModel(),
        vad=vad,
        preemptive_generation=True,
    )
    
    # Start with audio enhancement
    await session.start(
        agent=Assistant(),
        room=ctx.room,
        room_options=room_io.RoomOptions(
            audio_input=room_io.AudioInputOptions(
                noise_cancellation=ai_coustics.audio_enhancement(
                    model=ai_coustics.EnhancerModel.QUAIL_VF_S
                ),
            ),
        ),
    )
    
    # Connect to room and start listening
    await ctx.connect()
```

--------------------------------

### Complete AgentServer Setup with Prewarming and Logging

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/agent-server.md

This example demonstrates a full AgentServer setup, including a prewarming function to load a VAD model, registering an agent handler with custom logging fields, and initializing an AgentSession. It shows how to retrieve prewarmed resources and integrate with the LiveKit CLI.

```python
from livekit.agents import AgentServer, JobContext, JobProcess, cli
from livekit.plugins import silero

import logging

logger = logging.getLogger("agent")

server = AgentServer()

def prewarm(proc: JobProcess):
    """Load VAD model once per process"""
    logger.info("Prewarming VAD model...")
    proc.userdata["vad"] = silero.VAD.load()

server.setup_fnc = prewarm

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    # Add custom logging context
    ctx.log_context_fields = {
        "room": ctx.room.name,
        "participant_count": len(ctx.room.participants),
    }
    
    # Retrieve prewarmed VAD from userdata
    vad = ctx.proc.userdata["vad"]
    
    # Initialize agent session
    session = AgentSession(
        stt=inference.STT(model="deepgram/nova-3", language="multi"),
        tts=inference.TTS(model="cartesia/sonic-3", voice="..."),
        vad=vad,
    )
    
    # Start the session with the agent
    await session.start(agent=Assistant(), room=ctx.room)
    
    # Connect to the room and start listening/speaking
    await ctx.connect()

if __name__ == "__main__":
    cli.run_app(server)
```

--------------------------------

### Basic AudioOutputOptions Example

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/room-io.md

Instantiates AudioOutputOptions and includes it in RoomOptions for basic outgoing audio setup.

```python
output_opts = room_io.AudioOutputOptions(
    sample_rate=24000,
    num_channels=1,
)

room_options = room_io.RoomOptions(audio_output=output_opts)
```

--------------------------------

### Clone and Install Agent Starter Project

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/quick-start.md

Clone the agent-starter-python repository and install its dependencies using uv.

```bash
# Clone the repository
git clone https://github.com/livekit-examples/agent-starter-python.git
cd agent-starter-python

# Install dependencies
uv sync
```

--------------------------------

### Install Dependencies

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/index.md

Use this command to install project dependencies.

```bash
# Install dependencies
uv sync
```

--------------------------------

### Install Local Plugin

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/modules.md

Demonstrates how to install a custom plugin developed locally using `uv add`. This is for creating reusable components as plugins.

```bash
uv add ./livekit-plugins-my-feature

```

--------------------------------

### Install Essential Plugins

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/plugins.md

Installs the core LiveKit Agents with Silero and Turn Detector, and the AI Acoustics plugin. These are typically pre-installed in the starter project.

```bash
# Already installed in starter project
uv add livekit-agents[silero,turn-detector]
uv add livekit-plugins-ai-coustics
```

--------------------------------

### Test Framework Setup

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/testing.md

Basic setup for tests using pytest and async support. Imports necessary modules for agent testing.

```python
import pytest
from livekit.agents import AgentSession, inference, llm

# Tests are automatically async via pytest-asyncio
@pytest.mark.asyncio
async def test_example():
    # Test code here
    pass
```

--------------------------------

### Install Dependencies

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/README.md

Installs project dependencies using uv sync.

```bash
uv sync
```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/cli.md

Clone the repository and install project dependencies using uv.

```bash
# Clone repository
git clone <repo-url>
cd agent-starter-python

# Install dependencies
uv sync
```

--------------------------------

### Install Dependencies Manually

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/README.md

Clone the repository and install project dependencies using uv.

```console
cd agent-starter-python
uv sync
```

--------------------------------

### Basic AgentServer Setup

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/agent-server.md

This snippet shows the fundamental setup of an AgentServer, including defining an optional prewarming function and registering an RTC session handler using the @server.rtc_session decorator. It's suitable for basic agent configurations.

```python
from livekit.agents import AgentServer, JobContext, JobProcess

# Create the server instance
server = AgentServer()

# Define a prewarming function (optional)
def prewarm(proc: JobProcess):
    # Load models, initialize resources here
    proc.userdata["vad"] = silero.VAD.load()

# Attach the prewarming function
server.setup_fnc = prewarm

# Register RTC session handlers using decorator
@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    # Agent initialization and execution
    await ctx.connect()

# Run the server
if __name__ == "__main__":
    cli.run_app(server)
```

--------------------------------

### Run Agent Start Command

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/cli.md

Use the `start` command for production deployment of your agent. It runs the agent server in production mode, connecting to LiveKit Cloud for job processing and handling multiple concurrent sessions.

```bash
python src/agent.py start
```

--------------------------------

### Assistant Initialization and AgentSession Start

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/assistant.md

Initializes the Assistant and starts an AgentSession. Requires STT, TTS, turn detection, VAD, and preemptive generation to be configured.

```python
from agent import Assistant

# Initialize the assistant
assistant = Assistant()

# Use within an AgentSession
session = AgentSession(
    stt=inference.STT(model="deepgram/nova-3", language="multi"),
    tts=inference.TTS(model="cartesia/sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"),
    turn_detection=MultilingualModel(),
    vad=vad_instance,
    preemptive_generation=True,
)
await session.start(agent=assistant, room=ctx.room)
```

--------------------------------

### Complete Agent Session Handler Pattern

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/job-context.md

A comprehensive example demonstrating the setup of an AgentServer, prewarming resources, defining an RTC session handler with logging, prewarmed resource access, session configuration, and connection.

```python
from livekit.agents import AgentServer, JobContext, JobProcess, cli
from livekit.agents.agent_session import AgentSession
from livekit.agents.assistant import Assistant
import silero
import logging

logger = logging.getLogger(__name__)

server = AgentServer()

def prewarm(proc: JobProcess):
    """Called once per process to warm up resources"""
    proc.userdata["vad"] = silero.VAD.load()

server.setup_fnc = prewarm

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    # Set up logging
    ctx.log_context_fields = {
        "room": ctx.room.name,
    }
    
    # Access prewarmed VAD
    vad = ctx.proc.userdata["vad"]
    
    # Create and configure session
    session = AgentSession(
        stt=inference.STT(model="deepgram/nova-3", language="multi"),
        tts=inference.TTS(model="cartesia/sonic-3", voice="..."),
        vad=vad,
    )
    
    # Start the session
    await session.start(
        agent=Assistant(),
        room=ctx.room,
    )
    
    # This blocks until the session ends
    await ctx.connect()

if __name__ == "__main__":
    cli.run_app(server)
```

--------------------------------

### Install LiveKit CLI on Linux

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/README.md

Installs the LiveKit CLI on Linux systems by downloading and executing a script.

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

--------------------------------

### AgentSession.start()

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/agent-session.md

Initializes and starts the voice pipeline for the agent session.

```APIDOC
## AgentSession.start()

### Description
Initializes and starts the voice pipeline, connecting the agent and room for a voice conversation.

### Method
async

### Endpoint
None (Method call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **agent** (`Agent`) - Required - The agent instance to use (e.g., Assistant)
- **room** (`Room`) - Required - The LiveKit room instance
- **room_options** (`RoomOptions`) - Optional - Configuration for room audio input/output

### Request Example
```python
session = AgentSession(
    stt=inference.STT(model="deepgram/nova-3", language="multi"),
    tts=inference.TTS(model="cartesia/sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"),
    vad=silero_vad,
    turn_detection=MultilingualModel(),
    preemptive_generation=True,
)

await session.start(
    agent=Assistant(),
    room=ctx.room,
    room_options=room_io.RoomOptions(
        audio_input=room_io.AudioInputOptions(
            noise_cancellation=ai_coustics.audio_enhancement(
                model=ai_coustics.EnhancerModel.QUAIL_VF_S
            ),
        ),
    ),
)
```

### Response
#### Success Response (None)
None

#### Response Example
None

### Error Handling
- `RuntimeError` - If room is not available or models fail to initialize
```

--------------------------------

### Docker Usage for Production Start

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/cli.md

This Dockerfile command specifies how to run the agent in production mode using `uv` and the `start` command. Ensure LiveKit credentials are set via environment variables.

```dockerfile
CMD ["uv", "run", "src/agent.py", "start"]
```

--------------------------------

### openai.realtime.RealtimeModel

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/plugins.md

Creates a realtime model instance for ultra-low-latency conversations using OpenAI's Realtime API. Requires specific installation and environment setup.

```APIDOC
## openai.realtime.RealtimeModel

Creates a realtime model instance for ultra-low-latency conversations.

### Description

Initializes a `RealtimeModel` object that leverages OpenAI's Realtime API to provide synthesized responses with minimal latency. This is an alternative to the standard `inference.LLM` for agents requiring near-instantaneous audio feedback.

### Constructor

```python
class RealtimeModel:
    def __init__(self, voice: str)
```

### Parameters

*   **voice** (str) - Required - The identifier for the desired voice to be used for speech synthesis (e.g., "marin", "alloy").

### Usage Example

```python
from livekit.plugins import openai

# Use the realtime model instead of a standard LLM
llm = openai.realtime.RealtimeModel(voice="marin")

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            llm=llm,  # Assign the realtime model here
            instructions="...",
        )
```

### Notes and Setup

When utilizing realtime models:
1.  Ensure Speech-to-Text (STT) and Text-to-Speech (TTS) are removed from `AgentSession` configuration.
2.  Install the necessary plugin:
    ```bash
    uv add livekit-agents[openai]
    ```
3.  Set the `OPENAI_API_KEY` environment variable with your OpenAI API key.
```

--------------------------------

### Run Agent Behavior Tests

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/index.md

Provides an example of how to test agent behavior using `pytest` and `AgentSession`. It shows starting an agent, running user input, and asserting expected message events.

```python
import pytest
from livekit.agents import AgentSession

@pytest.mark.asyncio
async def test_agent_behavior():
    async with AgentSession() as session:
        await session.start(MyAssistant())
        result = await session.run(user_input="Hello")
        await result.expect.next_event().is_message(role="assistant")
        result.expect.no_more_events()
```

--------------------------------

### Complete Import Example

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/modules.md

Demonstrates the necessary imports for the LiveKit Agent Starter Python project, including standard library, third-party, LiveKit core, and LiveKit plugins. Ensure environment variables are loaded.

```python
# Standard library
import logging
import textwrap

# Third-party
from dotenv import load_dotenv

# LiveKit core
from livekit.agents (
    Agent,
    AgentServer,
    AgentSession,
    JobContext,
    JobProcess,
    cli,
    inference,
    room_io,
    function_tool,
    RunContext,
)

# LiveKit plugins
from livekit.plugins import ai_coustics, silero
from livekit.plugins.turn_detector.multilingual import MultilingualModel

# Configuration
load_dotenv(".env.local")

logger = logging.getLogger("agent")

# Now ready to use all components

```

--------------------------------

### Configure Environment Variables

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/quick-start.md

Copy the example environment file and edit it with your LiveKit and OpenAI API credentials.

```bash
# Copy example to local
cp .env.example .env.local

# Edit .env.local with your credentials
# Required:
LIVEKIT_URL=wss://your-server.livekit.io
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret
OPENAI_API_KEY=sk-...
```

--------------------------------

### Lookup Weather Function Tool Example

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/function-tools.md

An example of a function tool that looks up weather information. The docstring guides the LLM on usage, error handling, and parameter documentation.

```python
@function_tool
async def lookup_weather(self, context: RunContext, location: str):
    """Use this tool to look up current weather information in the given location.
    
    If the location is not supported by the weather service, the tool will indicate this.
    You must tell the user the location's weather is unavailable.
    
    Args:
        location: The location to look up weather information for (e.g. city name)
    """
    logger.info(f"Looking up weather for {location}")
    return "sunny with a temperature of 70 degrees."
```

--------------------------------

### Install LiveKit CLI on Windows

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/README.md

Installs the LiveKit CLI on Windows systems using the winget package manager.

```powershell
winget install LiveKit.LiveKitCLI
```

--------------------------------

### Python System Instructions for Tools

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/function-tools.md

Example of system instructions for an Agent, documenting available tools and outlining output rules and tool guidelines for the LLM.

```python
instructions=textwrap.dedent("""
    You are a helpful assistant with access to the following tools:
    - weather lookup: Get current weather for any location
    - currency conversion: Convert between common currencies
    
    Use these tools to help the user accomplish their tasks.
    When using tools, confirm the action before proceeding when appropriate.
    If a tool fails, inform the user and offer alternatives.
    
    # Output rules
    - Respond in plain text only
    - Keep replies brief: 1-3 sentences
    - Spell out numbers
    
    # Tool guidelines
    - Always tell the user what tool you're using
    - Confirm tool results before presenting them
    - If a tool isn't available for their request, say so clearly
"""),
```

--------------------------------

### Start AgentSession and Connect to Room

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/agent-session.md

Starts the voice pipeline and connects to a LiveKit room. Configure audio input options like noise cancellation.

```python
session = AgentSession(
    stt=inference.STT(model="deepgram/nova-3", language="multi"),
    tts=inference.TTS(model="cartesia/sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"),
    vad=silero_vad,
    turn_detection=MultilingualModel(),
    preemptive_generation=True,
)

await session.start(
    agent=Assistant(),
    room=ctx.room,
    room_options=room_io.RoomOptions(
        audio_input=room_io.AudioInputOptions(
            noise_cancellation=ai_coustics.audio_enhancement(
                model=ai_coustics.EnhancerModel.QUAIL_VF_S
            ),
        ),
    ),
)
```

--------------------------------

### Install Optional Plugins

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/plugins.md

Installs optional plugins for advanced features. Use the OpenAI plugin for real-time models and the Anam plugin for avatar integration.

```bash
# Optional plugins
uv add livekit-agents[openai]  # For realtime models
uv add livekit-plugins-anam     # For avatars
```

--------------------------------

### Complete Function Tool Example

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/function-tools.md

An example of a Python agent utilizing function tools for weather lookup and currency conversion. This agent is configured with an LLM and custom instructions.

```python
from livekit.agents import Agent, function_tool, RunContext
import logging

logger = logging.getLogger("agent")

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            llm=inference.LLM(model="openai/gpt-5.2-chat-latest"),
            instructions=textwrap.dedent("""
                You are a helpful assistant with access to tools.
                Use available tools to help the user.
            """),
        )
    
    @function_tool
    async def lookup_weather(self, context: RunContext, location: str):
        """Use this tool to look up current weather information in the given location.
        
        If the location is not supported by the weather service, the tool will indicate this.
        You must tell the user the location's weather is unavailable.
        
        Args:
            location: The location to look up weather information for (e.g. city name)
        """
        logger.info(f"Looking up weather for {location}")
        
        # Simulate weather lookup
        if location.lower() in ["new york", "los angeles"]:
            return f"Weather in {location}: sunny with a temperature of 70 degrees."
        else:
            return f"Weather data not available for {location}"
    
    @function_tool
    async def convert_currency(
        self, context: RunContext, amount: float, from_currency: str, to_currency: str
    ) -> str:
        """Convert an amount from one currency to another.
        
        Supports common currencies like USD, EUR, GBP, JPY, etc.
        
        Args:
            amount: The amount to convert
            from_currency: The source currency code (e.g. USD)
            to_currency: The target currency code (e.g. EUR)
        """
        logger.info(f"Converting {amount} {from_currency} to {to_currency}")
        
        # Simplified conversion rates
        rates = {"USD_EUR": 0.92, "EUR_USD": 1.09, "GBP_USD": 1.27}
        key = f"{from_currency}_{to_currency}"
        
        if key in rates:
            converted = amount * rates[key]
            return f"{amount} {from_currency} = {converted:.2f} {to_currency}"
        else:
            return f"Conversion between {from_currency} and {to_currency} not supported"
```

--------------------------------

### Install LiveKit CLI on macOS

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/README.md

Installs the LiveKit CLI using Homebrew on macOS systems.

```bash
brew install livekit-cli
```

--------------------------------

### Integrating Room Options with Agent Session

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/room-io.md

Demonstrates how to pass custom room options, including audio enhancement, when starting an Agent Session.

```python
session = AgentSession(
    stt=inference.STT(model="deepgram/nova-3", language="multi"),
    tts=inference.TTS(model="cartesia/sonic-3", voice="..."),
    vad=vad,
    turn_detection=turn_detector,
)

await session.start(
    agent=Assistant(),
    room=ctx.room,
    room_options=room_io.RoomOptions(
        audio_input=room_io.AudioInputOptions(
            noise_cancellation=ai_coustics.audio_enhancement(
                model=ai_coustics.EnhancerModel.QUAIL_VF_S
            ),
        ),
    ),
)
```

--------------------------------

### Run Agent in Production Mode

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/README.md

Execute the agent script using the 'start' command for production deployment.

```bash
uv run python src/agent.py start
```

--------------------------------

### Create a LiveKit Agent Server

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/index.md

Sets up an `AgentServer` and defines an RTC session handler. This handler instantiates and starts a custom agent, then connects to the session.

```python
from livekit.agents import AgentServer

server = AgentServer()

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    session = AgentSession(...)
    await session.start(agent=MyAssistant(), room=ctx.room)
    await ctx.connect()

if __name__ == "__main__":
    cli.run_app(server)
```

--------------------------------

### Configure LiveKit URL

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/quick-start.md

Check if the .env.local file exists and is configured with your LiveKit credentials. If it's missing, copy the example file and edit it.

```bash
# Check .env.local exists
cat .env.local

# If missing, create it
cp .env.example .env.local
# Edit with your credentials
```

--------------------------------

### Complete Voice Pipeline Setup

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/inference.md

Sets up a full inference pipeline including Speech-to-Text, Text-to-Speech, and a Large Language Model. This pipeline is then integrated into an AgentSession.

```python
from livekit.agents import inference, AgentSession

# Create the complete inference pipeline
stt = inference.STT(model="deepgram/nova-3", language="multi")
tts = inference.TTS(model="cartesia/sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc")
llm = inference.LLM(model="openai/gpt-5.2-chat-latest")

# Use in agent
assistant = Assistant()  # Uses LLM from constructor

# Use in session
session = AgentSession(
    stt=stt,
    tts=tts,
)
await session.start(agent=assistant, room=ctx.room)
```

--------------------------------

### Run Agent in Development Mode

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/README.md

Start the agent for use with a frontend or telephony during development.

```bash
uv run python src/agent.py dev
```

--------------------------------

### Agent CLI Startup Output

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/cli.md

This is a typical output log when starting the agent server. It shows connection status, agent session details, and model information.

```text
2024-06-16 10:00:00 Starting agent server...
2024-06-16 10:00:01 Connecting to LiveKit: wss://your-server.livekit.io
2024-06-16 10:00:02 Agent server ready for jobs
2024-06-16 10:00:05 [my-agent] New session: room="daily-standup", participants=3
2024-06-16 10:00:06 [my-agent] STT model: deepgram/nova-3
2024-06-16 10:00:06 [my-agent] TTS model: cartesia/sonic-3
2024-06-16 10:00:07 [my-agent] Agent session started
...
2024-06-16 10:05:00 [my-agent] Session ended
```

--------------------------------

### Complete Prewarming Example

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/job-process.md

This Python script sets up an agent server that prewarms VAD and turn detector models, along with a configuration dictionary. These resources are stored in `proc.userdata` and retrieved by new agent sessions to initialize an `AgentSession`.

```python
from livekit.agents import AgentServer, JobContext, JobProcess, cli
from livekit.plugins import silero
from livekit.plugins.turn_detector.multilingual import MultilingualModel
import logging

logger = logging.getLogger("agent")

server = AgentServer()

def prewarm(proc: JobProcess):
    """Load all expensive resources once per process"""
    logger.info("Prewarming process...")
    
    # Load VAD model
    logger.info("Loading VAD model...")
    proc.userdata["vad"] = silero.VAD.load()
    
    # Load turn detector model
    logger.info("Loading turn detector...")
    proc.userdata["turn_detector"] = MultilingualModel()
    
    # Load any other resources
    proc.userdata["config"] = {
        "max_message_length": 1000,
        "timeout_seconds": 30,
    }
    
    logger.info("Prewarming complete")

server.setup_fnc = prewarm

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    """Each session reuses the prewarmed resources"""
    ctx.log_context_fields = {"room": ctx.room.name}
    
    # Retrieve prewarmed resources
    vad = ctx.proc.userdata["vad"]
    turn_detector = ctx.proc.userdata["turn_detector"]
    config = ctx.proc.userdata["config"]
    
    logger.info(f"Using config: {config}")
    
    # Create session with prewarmed models
    session = AgentSession(
        stt=inference.STT(model="deepgram/nova-3", language="multi"),
        tts=inference.TTS(model="cartesia/sonic-3", voice="..."),
        vad=vad,
        turn_detection=turn_detector,
    )
    
    await session.start(agent=Assistant(), room=ctx.room)
    await ctx.connect()

if __name__ == "__main__":
    cli.run_app(server)

```

--------------------------------

### setup_fnc Signature

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/types.md

Defines the signature for a setup function, called once per process to load models and resources. It takes a 'proc: JobProcess' parameter.

```python
def setup_fnc(proc: JobProcess) -> None:
    # Load models and resources
    proc.userdata["key"] = value
```

--------------------------------

### Example LLM Tool Call

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/function-tools.md

Illustrates a user query, the LLM's decision to call a tool, the tool's return value, and the LLM's final response to the user.

```text
User: "What's the weather in Seattle?"

LLM: [calls lookup_weather("Seattle")]
Tool returns: "Weather in Seattle: cloudy with a temperature of 62 degrees."

LLM (to user): "The weather in Seattle is currently cloudy with a temperature of 62 degrees Fahrenheit."
```

--------------------------------

### Minimal Room Configuration

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/room-io.md

Starts a LiveKit agent session with default room options when no special audio processing is required. This configuration uses the system's default settings for audio input and output.

```python
# No room options needed - uses defaults
await session.start(
    agent=Assistant(),
    room=ctx.room,
    # room_options not specified - defaults applied
)
```

--------------------------------

### Initialize Realtime Model for Assistant

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/plugins.md

Initializes a realtime model instance for ultra-low-latency conversations using the OpenAI plugin. This replaces the standard LLM inference. Ensure the plugin is installed and the OpenAI API key is set.

```python
from livekit.plugins import openai

# Instead of inference.LLM, use realtime model
llm = openai.realtime.RealtimeModel(voice="marin")

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            llm=llm,  # Use realtime model instead
            instructions="...",
        )
```

--------------------------------

### Run Agent Download-Files Command

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/cli.md

Execute `download-files` to pre-download all necessary models and data files for your agent. This command caches ML model files locally and should be run before `dev` or `start` on a new machine.

```bash
python src/agent.py download-files
```

--------------------------------

### Run Agent Dev Command

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/cli.md

The `dev` command starts the agent in development mode, connecting to LiveKit Cloud. This is useful for testing with a web frontend and requires LiveKit credentials to be configured.

```bash
python src/agent.py dev
```

--------------------------------

### Development Mode

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/cli.md

Set up the environment and run the agent in development mode for frontend integration.

```bash
# Set up environment
cp .env.example .env.local
# Edit .env.local with your LiveKit credentials

# Run in dev mode
uv run python src/agent.py dev

# Frontend connects to the agent via LiveKit Cloud
# Test with web/mobile frontend
```

--------------------------------

### Initialize Agent with LiveKit CLI

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/README.md

Use the LiveKit CLI to create a new agent project from the agent-starter-python template.

```bash
lk cloud auth
lk agent init my-agent --template agent-starter-python
```

--------------------------------

### Complete .env.local Template

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/configuration.md

This template lists all required and optional environment variables for configuring the Agent Starter Python project. Ensure you replace placeholder values with your actual credentials and settings.

```bash
# Required
LIVEKIT_URL=wss://your-server.livekit.io
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret

# Model providers
OPENAI_API_KEY=sk-your-openai-key
DEEPGRAM_API_KEY=your-deepgram-key
CARTESIA_API_KEY=your-cartesia-key

# Optional
LOG_LEVEL=INFO
DEBUG=false
```

--------------------------------

### Required Environment Variables for CLI

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/cli.md

Essential environment variables for development and starting the agent.

```bash
LIVEKIT_URL=wss://your-livekit-server.example.com
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret
```

--------------------------------

### Process Lifecycle Overview

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/job-process.md

Illustrates the sequence of events from server startup to session management within a worker process, highlighting model prewarming and reuse.

```text
1. Server starts
2. create_worker_process()
   └─ prewarm(proc) runs
      └─ Models loaded into proc.userdata
3. Session 1 starts
   └─ ctx.proc.userdata accessible
   └─ Reuses prewarmed models
4. Session 1 ends
   └─ Process stays alive
5. Session 2 starts
   └─ ctx.proc.userdata still available
   └─ Reuses same prewarmed models
6. [... more sessions ...]
7. Worker process shuts down
   └─ All userdata cleaned up
```

--------------------------------

### Project Structure Overview

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/index.md

This snippet outlines the directory structure of the agent-starter-python project. It shows the organization of source code, tests, configuration files, and deployment artifacts.

```text
agent-starter-python/
├── src/
│   ├── __init__.py          # Package marker
│   └── agent.py             # Main agent implementation
├── tests/
│   └── test_agent.py        # Agent behavior tests
├── pyproject.toml           # Python project configuration
├── Dockerfile               # Production deployment
├── .env.example             # Environment template
└── README.md                # Quick start guide
```

--------------------------------

### anam.AvatarSession

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/plugins.md

Creates a visual avatar session for agent representation. Requires installation of the livekit-plugins-anam package.

```APIDOC
## anam.AvatarSession

Creates a visual avatar session.

### Description

Instantiates an `AvatarSession` object to manage a virtual avatar for an agent. This allows for visual representation within a LiveKit room.

### Usage

```python
from livekit.plugins import anam

avatar = anam.AvatarSession(
    persona_config=anam.PersonaConfig(
        name="My Assistant",
        avatarId="...",  # Obtain from Anam documentation
    ),
)
await avatar.start(session, room=ctx.room)
```

### Parameters

*   **persona_config** (anam.PersonaConfig) - Required - Configuration for the agent's persona, including name and avatar ID.

### Installation

To use this plugin, install it via pip:
```bash
uv add livekit-plugins-anam
```
```

--------------------------------

### Complete Audio Configuration with Enhancements

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/room-io.md

Demonstrates a full audio configuration for an AgentSession, including noise cancellation for input and specific sample rates for input and output.

```python
from livekit.agents import AgentSession, room_io
from livekit.plugins import ai_coustics

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    # Configure audio processing
    room_options = room_io.RoomOptions(
        audio_input=room_io.AudioInputOptions(
            # Apply noise cancellation to incoming audio
            noise_cancellation=ai_coustics.audio_enhancement(
                model=ai_coustics.EnhancerModel.QUAIL_VF_S
            ),
            sample_rate=16000,  # Standard for speech recognition
            num_channels=1,     # Mono audio
        ),
        audio_output=room_io.AudioOutputOptions(
            sample_rate=24000,  # Standard for TTS
            num_channels=1,     # Mono output
        ),
    )
    
    # Create session
    session = AgentSession(
        stt=inference.STT(model="deepgram/nova-3", language="multi"),
        tts=inference.TTS(model="cartesia/sonic-3", voice="..."),
    )
    
    # Start with audio configuration
    await session.start(
        agent=Assistant(),
        room=ctx.room,
        room_options=room_options,
    )
    
    await ctx.connect()
```

--------------------------------

### Create an Avatar Session

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/plugins.md

Creates a visual avatar session using the Anam plugin. Ensure the plugin is installed before use.

```python
from livekit.plugins import anam

avatar = anam.AvatarSession(
    persona_config=anam.PersonaConfig(
        name="My Assistant",
        avatarId="...",  # From Anam documentation
    ),
)
await avatar.start(session, room=ctx.room)
```

--------------------------------

### Run Pytest for Agent Evals

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/README.md

Execute the test suite for the LiveKit Agents using pytest. Ensure you have pytest installed and configured.

```console
uv run pytest
```

--------------------------------

### Configuration File: .env.local

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/cli.md

Configuration file for LiveKit connection and optional model providers.

```bash
# Required for cloud connection
LIVEKIT_URL=
LIVEKIT_API_KEY=
LIVEKIT_API_SECRET=

# Optional model providers
OPENAI_API_KEY=
DEEPGRAM_API_KEY=
CARTESIA_API_KEY=
```

--------------------------------

### silero.VAD.load

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/plugins.md

Loads the Silero Voice Activity Detection (VAD) model. This is a computationally expensive operation and should ideally be performed once during process setup.

```APIDOC
## silero.VAD.load

### Description
Loads the Silero VAD model. This method is used to initialize the Voice Activity Detection functionality.

### Method
```python
@staticmethod
def load() -> VAD
```

### Parameters
(none)

### Return Type
`silero.VAD` instance

### Example
```python
from livekit.plugins import silero

# Load during prewarming for better performance
proc.userdata["vad"] = silero.VAD.load()
```
```

--------------------------------

### Disable Audio Enhancement

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/quick-start.md

To disable audio enhancement, simply omit the `room_options` parameter or ensure `audio_input` is not configured when starting the session.

```python
await session.start(
    agent=Assistant(),
    room=ctx.room,
)
```

--------------------------------

### Setting Custom Log Context Fields

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/job-context.md

Enrich log entries with custom fields by assigning a dictionary to `ctx.log_context_fields` at the start of the handler.

```python
from livekit.agents import server, JobContext
import logging

logger = logging.getLogger(__name__)

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    ctx.log_context_fields = {
        "room": ctx.room.name,
        "user_id": ctx.room.metadata,
        "agent_version": "1.0.0",
    }
    
    logger.info("Session started")  # Will include all log_context_fields
```

--------------------------------

### Load Silero VAD Model

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/plugins.md

Loads the Silero Voice Activity Detection model. This should be done once per process during setup for optimal performance.

```python
from livekit.plugins import silero

def prewarm(proc: JobProcess):
    # Load during prewarming for better performance
    proc.userdata["vad"] = silero.VAD.load()

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    vad = ctx.proc.userdata["vad"]
    session = AgentSession(vad=vad)
```

--------------------------------

### List Available LiveKit CLI Commands

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/README.md

Use the '--help' flag with the 'lk docs' command to list all available commands.

```bash
# List available commands
lk docs --help
```

--------------------------------

### Full Audio Configuration

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/types.md

Instantiates RoomOptions with all audio input and output options specified, including noise cancellation, sample rates, and channel counts.

```python
RoomOptions(
    audio_input=AudioInputOptions(
        noise_cancellation=AudioEnhancer,
        sample_rate=16000,
        num_channels=1,
    ),
    audio_output=AudioOutputOptions(
        sample_rate=24000,
        num_channels=1,
    ),
)
```

--------------------------------

### Run Pytest with Verbose Output

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/testing.md

Use the -v flag to get detailed output from pytest, helpful for understanding test execution flow.

```bash
uv run pytest -v tests/test_agent.py::test_name
```

--------------------------------

### Project Configuration with pyproject.toml

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/configuration.md

Defines project metadata, dependencies, and tool configurations for the agent starter project. Ensure dependencies like livekit-agents and python-dotenv are included.

```toml
[project]
name = "agent-starter-python"
version = "1.0.0"
requires-python = ">=3.10, <3.15"

[project.dependencies]
livekit-agents[silero,turn-detector]>=1.6.0
livekit-plugins-ai-coustics~=0.2
python-dotenv

[tool.pytest.ini_options]
asyncio_mode = "auto"

[tool.ruff]
line-length = 88
target-version = "py39"

```

--------------------------------

### Pre-warming Resources with JobProcess

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/job-process.md

Demonstrates how to load resources like VAD models and configurations once per process using `proc.userdata`. These loaded resources can then be accessed by any session within that process.

```python
def prewarm(proc: JobProcess):
    """Load models once per process"""
    proc.userdata["vad"] = silero.VAD.load()
    proc.userdata["config"] = load_config()

server.setup_fnc = prewarm

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    # Access data from all previous sessions in this process
    vad = ctx.proc.userdata["vad"]
    config = ctx.proc.userdata["config"]
```

--------------------------------

### Enable Preemptive Generation

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/agent-session.md

Set preemptive generation to True to allow the LLM to start generating responses while the user is still speaking, reducing latency.

```python
preemptive_generation=True
```

--------------------------------

### Initialize Virtual Avatar Session

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/agent-session.md

Use this snippet to add a visual avatar to your agent session. Ensure you have the anam plugin installed and refer to LiveKit documentation for avatarId.

```python
from livekit.plugins import anam

avatar = anam.AvatarSession(
    persona_config=anam.PersonaConfig(
        name="Assistant Name",
        avatarId="...",  # See LiveKit documentation
    ),
)
await avatar.start(session, room=ctx.room)
```

--------------------------------

### Minimal Audio Configuration

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/types.md

Instantiates RoomOptions with default audio settings. This is the most basic configuration.

```python
RoomOptions()
```

--------------------------------

### Realtime Model LLM Configuration

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/assistant.md

Replaces the default LLM with a realtime model, such as OpenAI's Realtime API. Requires installing the relevant plugin and setting API keys.

```python
llm=openai.realtime.RealtimeModel(voice="marin")
```

--------------------------------

### Assistant Constructor

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/assistant.md

Initializes the Assistant class. All configuration is hardcoded in the initialization logic and takes no parameters.

```APIDOC
## Assistant Constructor

```python
def __init__(self) -> None
```

### Description

Initializes the Assistant class. All configuration is hardcoded in the initialization logic and takes no parameters.

### Parameters

(none)

### Return Type

Returns an instance of `Assistant` configured with:
- LLM model: OpenAI GPT-5.2 Chat Latest
- System instructions focused on voice-based interaction with safety guidelines
- No additional tools (base implementation)
```

--------------------------------

### Configure Audio Enhancement for Input

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/agent-session.md

Set up room options to apply audio enhancement, such as noise cancellation using the QUAIL_VF_S model.

```python
room_options=room_io.RoomOptions(
    audio_input=room_io.AudioInputOptions(
        noise_cancellation=ai_coustics.audio_enhancement(
            model=ai_coustics.EnhancerModel.QUAIL_VF_S
        ),
    ),
)
```

--------------------------------

### Change STT Model in AgentSession

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/quick-start.md

Modify the `stt` parameter in the `AgentSession` initialization to switch the Speech-to-Text model. Examples include using OpenAI Whisper or the default Deepgram model.

```python
session = AgentSession(
    # Change this line:
    stt=inference.STT(model="openai/whisper-1", language="en"),  # OpenAI Whisper
    # or
    stt=inference.STT(model="deepgram/nova-3", language="multi"),  # Default (multilingual)
    tts=inference.TTS(model="cartesia/sonic-3", voice="..."),
)
```

--------------------------------

### Test Agent Feature Evaluation

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/testing.md

Use this template to test a specific agent feature. It starts an AgentSession, runs user input, and evaluates the assistant's response for correctness and intent.

```python
import pytest
from livekit.ai.agent.session import AgentSession
from livekit.ai.agent.types import Assistant

# Assume _judge_llm and AgentSession are defined elsewhere

@pytest.mark.asyncio
async def test_your_feature() -> None:
    """Clear description of what the test evaluates."""
    async with (
        _judge_llm() as judge_llm,
        AgentSession() as session,
    ):
        await session.start(Assistant())
        
        result = await session.run(user_input="Your test input")
        
        # Evaluate the response
        await (
            result.expect.next_event()
            .is_message(role="assistant")
            .judge(
                judge_llm,
                intent="Detailed description of the expected behavior",
            )
        )
        
        # Ensure no unexpected tool calls or events
        result.expect.no_more_events()
```

--------------------------------

### Configure Room Audio Input and Output Options

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/room-io.md

Sets up room-level audio processing options, including noise cancellation for audio input. This is useful for customizing how audio is handled within a LiveKit room session.

```python
from livekit.agents import room_io
from livekit.plugins import ai_coustics

room_options = room_io.RoomOptions(
    audio_input=room_io.AudioInputOptions(
        noise_cancellation=ai_coustics.audio_enhancement(
            model=ai_coustics.EnhancerModel.QUAIL_VF_S
        ),
    ),
)

await session.start(
    agent=Assistant(),
    room=ctx.room,
    room_options=room_options,
)
```

--------------------------------

### Enable Preemptive Generation

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/configuration.md

Enable preemptive generation in `AgentSession` to allow the LLM to generate responses while waiting for the end of a user's turn. This reduces perceived latency by starting generation earlier.

```python
session = AgentSession(
    preemptive_generation=True,
)
```

--------------------------------

### Agent System Instructions Configuration

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/configuration.md

Customize agent behavior by modifying the 'instructions' parameter during Assistant initialization.

```python
Assistant.__init__()
```

--------------------------------

### Production Docker Deployment

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/cli.md

Build a Docker image and run the agent in production mode.

```bash
# Build Docker image
docker build -t my-agent:latest .

# Run container
docker run \
  -e LIVEKIT_URL=wss://... \
  -e LIVEKIT_API_KEY=... \
  -e LIVEKIT_API_SECRET=... \
  my-agent:latest

# Agent starts in production mode
# Processes jobs from LiveKit Cloud
```

--------------------------------

### Store Session-Specific Data with JobContext

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/job-process.md

Use `ctx` within an `rtc_session` to store data that is only available for the current session. This is useful for tracking session-specific information like start times or user IDs.

```python
from datetime import datetime
from livekit.agents import JobContext

# Assume server and logger are imported and configured
# Assume extract_user_id is defined elsewhere

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    # Session-specific (not shared)
    session_data = {
        "start_time": datetime.now(),
        "user_id": extract_user_id(ctx.room),
    }
    
    # Access in nested functions
    logger.info(f"Session started at {session_data['start_time']}")
```

--------------------------------

### Run Agent in Development Mode

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/quick-start.md

Launch the agent in development mode to connect to LiveKit Cloud and test with a frontend or mobile app.

```bash
# Connect to LiveKit Cloud
uv run python src/agent.py dev

# Frontend/mobile app connects via LiveKit
# Test with web or mobile interface
```

--------------------------------

### Tool with Error Handling

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/api-reference/function-tools.md

Shows how to implement error handling within a tool to provide user-friendly messages. This example includes handling specific API errors and value errors during a weather lookup.

```python
@function_tool
async def lookup_weather(self, context: RunContext, location: str):
    """Look up weather for a location."""
    try:
        # Attempt API call
        result = await weather_api.get(location)
        return f"Weather in {location}: {result}"
    except WeatherAPIError as e:
        logger.error(f"Weather API error: {e}")
        return f"Unable to get weather for {location}. Please try again later."
    except ValueError:
        return f"'{location}' is not a valid location."
```

--------------------------------

### Enable Audio Enhancement (Noise Cancellation)

Source: https://github.com/livekit-examples/agent-starter-python/blob/main/_autodocs/quick-start.md

To enable audio enhancement like noise cancellation, add the `noise_cancellation` option within `room_io.AudioInputOptions` during session start. This uses AI acoustics models for enhancement.

```python
await session.start(
    agent=Assistant(),
    room=ctx.room,
    room_options=room_io.RoomOptions(
        audio_input=room_io.AudioInputOptions(
            # Add this to enable noise cancellation
            noise_cancellation=ai_coustics.audio_enhancement(
                model=ai_coustics.EnhancerModel.QUAIL_VF_S
            ),
        ),
    ),
)
```