LiveKit Agents

https://docs.livekit.io/agents/
Admin
LiveKit Agents is a realtime framework for building voice, video, and physical AI agents in Python...
Tokens:614,910
Snippets:4,962
Trust Score:9.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Clone and install hello-wakeword example

Source: https://docs.livekit.io/agents/multimodality/audio/wakeword

Clones the hello-wakeword example repository and installs all packages using uv. Requires uv to be installed.

```bash
git clone https://github.com/livekit-examples/hello-wakeword
cd hello-wakeword
uv sync --all-packages
```

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

### Start the agent server

Source: https://docs.livekit.io/agents/multimodality/audio/wakeword

Starts the agent server in development mode for the wakeword-agent example.

```bash
lk agent dev wakeword-agent
```

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

### Installation

Source: https://docs.livekit.io/agents/models/stt/plugins/gemini

Install the plugin from PyPI using uv.

```APIDOC
## Installation

```bash
uv add "livekit-agents[google]~=1.8"
```
```

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

### Use Ultravox RealtimeModel in AgentSession

Source: https://docs.livekit.io/agents/models/realtime/plugins/ultravox

Import the Ultravox plugin and create an AgentSession with the RealtimeModel. This example shows the minimal setup for using Ultravox in a Voice AI quickstart.

```python
from livekit.plugins import ultravox


session = AgentSession(
   llm=ultravox.realtime.RealtimeModel(),
)
```

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

### Installation

Source: https://docs.livekit.io/agents/models/tts/plugins/simplismart

Install the Simplismart TTS plugin from PyPI.

```APIDOC
## Installation

### Description
Install the Simplismart TTS plugin from PyPI.

### Command
```bash
uv add "livekit-agents[simplismart]~=1.8"
```
```

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

### Install ElevenLabs plugin (Python)

Source: https://docs.livekit.io/agents/models/tts/elevenlabs

Install the Python plugin from PyPI using uv.

```bash
uv add "livekit-agents[elevenlabs]~=1.8"
```

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

### Install agent dependencies (uv sync and pnpm install)

Source: https://docs.livekit.io/agents/start/voice-ai

Installs the agent's runtime and plugin dependencies. Use uv sync for Python projects and pnpm install for Node.js projects. Run these if you did not elect to have dependencies automatically installed during template setup.

```bash
uv sync
```

```bash
pnpm install
```

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

### Installation (Python)

Source: https://docs.livekit.io/agents/models/stt/plugins/assemblyai

Install the AssemblyAI plugin for Python using uv.

```APIDOC
## Installation (Python)

### Description
Install the AssemblyAI plugin for Python using uv.

### Command
```bash
uv add "livekit-agents[assemblyai]~=1.8"
```
```

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

### Install Python dependencies with uv

Source: https://docs.livekit.io/agents/start/voice-ai-quickstart

Install the agent's runtime and plugin dependencies if you did not elect to have them automatically installed during template setup.

```bash
uv sync
```

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

### Installation (Python)

Source: https://docs.livekit.io/agents/models/llm/spacexai

Install the SpaceXAI plugin for Python using uv.

```APIDOC
## Installation (Python)

### Command
```bash
uv add "livekit-agents[xai]~=1.8"
```
```

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

### Installation (Python)

Source: https://docs.livekit.io/agents/models/llm/plugins/deepseek

Install the LiveKit Agents OpenAI plugin with the DeepSeek support using uv.

```APIDOC
## Installation (Python)

### Description
Install the LiveKit Agents OpenAI plugin with DeepSeek support using uv.

### Command
```bash
uv add "livekit-agents[openai]~=1.8"
```
```

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

### Installation (Python)

Source: https://docs.livekit.io/agents/models/tts/plugins/inworld

Install the Inworld plugin for Python using uv.

```APIDOC
## Installation (Python)

### Description
Install the Inworld plugin for Python using uv.

### Command
```bash
uv add "livekit-agents[inworld]~=1.8"
```
```

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

### Installation (Python)

Source: https://docs.livekit.io/agents/models/llm/perplexity

Install the Perplexity plugin for Python using uv.

```APIDOC
## Installation (Python)

### Description
Install the Perplexity plugin for Python using uv.

### Command
```bash
uv add "livekit-agents[perplexity]~=1.8"
```
```

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

### Installation

Source: https://docs.livekit.io/agents/models/stt/cartesia

Install the Cartesia plugin from PyPI using uv.

```APIDOC
## Installation

### Command
```bash
uv add "livekit-agents[cartesia]~=1.8"
```
```

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

### Install AWS plugin

Source: https://docs.livekit.io/agents/integrations/aws

Install the LiveKit Agents AWS plugin using uv.

```bash
uv add "livekit-agents[aws]~=1.8"
```

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

### Installation (Node.js)

Source: https://docs.livekit.io/agents/models/llm/spacexai

Install the SpaceXAI plugin for Node.js using pnpm.

```APIDOC
## Installation (Node.js)

### Command
```bash
pnpm add @livekit/agents-plugin-openai@1.x
```
```

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

### Installation

Source: https://docs.livekit.io/agents/models/tts/plugins/slng

Install the SLNG TTS plugin using uv.

```APIDOC
## Installation

### Command
```bash
uv add "livekit-agents[slng]~=1.8"
```
```

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

### Install livekit-agents[spatius]

Source: https://docs.livekit.io/agents/models/avatar/plugins/spatius

Install the Spatius plugin for LiveKit Agents from PyPI using uv.

```bash
uv add "livekit-agents[spatius]~=1.8"
```

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

### Installation

Source: https://docs.livekit.io/agents/models/stt/speechmatics

Install the Speechmatics plugin from PyPI.

```APIDOC
## Installation

### Command
uv add "livekit-agents[speechmatics,silero]~=1.8"

### Description
Install the plugin from PyPI.
```

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

### Installation (Node.js)

Source: https://docs.livekit.io/agents/models/stt/plugins/assemblyai

Install the AssemblyAI plugin for Node.js using pnpm.

```APIDOC
## Installation (Node.js)

### Description
Install the AssemblyAI plugin for Node.js using pnpm.

### Command
```bash
pnpm add @livekit/agents-plugin-assemblyai@1.x
```
```

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

### Plugin Installation

Source: https://docs.livekit.io/agents/models/tts/fishaudio

Install the Fish Audio plugin for Python or Node.js.

```APIDOC
## [INSTALL] Plugin Installation

### Description
Install the LiveKit Fish Audio plugin package.

### Method
Package Manager

### Endpoint
N/A

### Parameters
#### Request Body
- **package_manager** (string) - Required - The package manager command to run (e.g., `uv add`, `pnpm add`)

### Request Example
```bash
# Python
uv add "livekit-agents[fishaudio]~=1.8"

# Node.js
pnpm add @livekit/agents-plugin-fishaudio@1.x
```

### Response
#### Success Response (200)
No response body. The plugin is installed.

#### Response Example
N/A
```

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

### Run agent in dev mode

Source: https://docs.livekit.io/agents/integrations/google

Starts the agent in dev mode to connect it to LiveKit and make it available from anywhere on the internet. Use the Agent Console to interact and debug in real-time; set the Agent name to 'my-agent' for this quickstart.

```bash
lk agent dev
```

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

### Configure AgentServer options in Python and Node.js

Source: https://docs.livekit.io/agents/server/options

Shows how to configure an AgentServer in Python and a ServerOptions instance in Node.js, including permissions, drain timeout, load threshold, setup/load functions, and log level. In Python, the server is started with cli.run_app(server); in Node.js, with cli.runApp(opts). The Python example notes that setup_fnc and load_fnc can be assigned directly on the instance instead of in the constructor.

```python
server = AgentServer(
    # Whether the agent can subscribe to tracks, publish data, update metadata, etc.
    permissions,
    # Amount of time to wait for existing jobs to finish when SIGTERM or SIGINT is received
    drain_timeout,
    # The maximum value of load_fnc, above which no new processes will spawn
    load_threshold,
    # A function to perform any necessary initialization before the job starts.
    setup_fnc,
    # Function to determine the current load of the worker. Should return a value between 0 and 1.
    load_fnc,
    # The log level for the agent server and its job processes. Defaults to 'info'.
    log_level,
)


# start the agent server
cli.run_app(server)
```

```javascript
const opts = new ServerOptions({
  // path to the agent module, which must export a default Agent object (usually the current file)
  agent: fileURLToPath(import.meta.url),
  // the agent name, used for explicit dispatch
  agentName: 'my-agent',
  // inspect the request and decide if the current agent server should handle it.
  requestFunc,
  // whether the agent can subscribe to tracks, publish data, update metadata, etc.
  permissions,
  // milliseconds to wait for existing jobs to finish when SIGTERM or SIGINT is received
  drainTimeout,
  // the type of agent server to create, either JT_ROOM or JT_PUBLISHER. Defaults to JT_ROOM.
  serverType: JobType.JT_ROOM,
  // a function that reports the current load of the agent server. returns a value between 0-1.
  loadFunc,
  // the maximum value of loadFunc, above which agent server is marked as unavailable.
  loadThreshold,
  // the log level for the agent server and its job processes. defaults to 'info'.
  logLevel: 'info',
})


// start the agent server
cli.runApp(opts);
```

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

### Installation

Source: https://docs.livekit.io/agents/models/llm/plugins/spacexai

Installation commands for the SpaceXAI plugin in Python and Node.js.

```APIDOC
## [INSTALL] Python

### Description
Install the SpaceXAI plugin for Python using uv.

### Command
```bash
uv add "livekit-agents[xai]~=1.8"
```
```

```APIDOC
## [INSTALL] Node.js

### Description
Install the SpaceXAI plugin for Node.js using pnpm.

### Command
```bash
pnpm add @livekit/agents-plugin-openai@1.x
```
```

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

### Install livekit-plugins-nvidia with PersonaPlex extra

Source: https://docs.livekit.io/agents/models/realtime/plugins/personaplex

Install the NVIDIA plugin with the PersonaPlex extra using uv.

```bash
uv add "livekit-plugins-nvidia[personaplex]"
```

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

### Installation (Node.js)

Source: https://docs.livekit.io/agents/models/tts/plugins/inworld

Install the Inworld plugin for Node.js using pnpm.

```APIDOC
## Installation (Node.js)

### Description
Install the Inworld plugin for Node.js using pnpm.

### Command
```bash
pnpm add @livekit/agents-plugin-inworld@1.x
```
```

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

### Installation (Node.js)

Source: https://docs.livekit.io/agents/models/llm/plugins/deepseek

Install the LiveKit Agents OpenAI plugin for Node.js using pnpm.

```APIDOC
## Installation (Node.js)

### Description
Install the LiveKit Agents OpenAI plugin for Node.js using pnpm.

### Command
```bash
pnpm add @livekit/agents-plugin-openai@1.x
```
```

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

### Install ElevenLabs plugin (Node.js)

Source: https://docs.livekit.io/agents/models/tts/elevenlabs

Install the Node.js plugin using pnpm.

```bash
pnpm add @livekit/agents-plugin-elevenlabs@1.x
```

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

### start

Source: https://docs.livekit.io/agents/multimodality/audio/background-audio

Starts the background audio player after room connection and agent session start. Begins ambient sound playback immediately.

```APIDOC
## start

### Description
Starts the background audio player. Must be called after room connection and agent session start. Ambient sounds begin playback immediately.

### Method
start

### Parameters
- **room** (Room) - Required - The connected room object.
- **agent_session** (AgentSession) - Required - The active agent session.

### Request Example
```python
await background_audio.start(room=ctx.room, agent_session=session)
```

### Response
No return value.
```

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

### Install livekit-agents[slng]

Source: https://docs.livekit.io/agents/models/stt/plugins/slng

Installs the SLNG plugin for LiveKit Agents. Requires Python and uv.

```bash
uv add "livekit-agents[slng]~=1.8"
```

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

### Use Keyframe avatar in AgentSession

Source: https://docs.livekit.io/agents/models/avatar/plugins/keyframe

Use the Keyframe avatar in an AgentSession. This example shows how to create an avatar, start it with the session and room, and then start the agent session. It can be used in the Voice AI quickstart.

```python
from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import keyframe


server = AgentServer()


@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
    session = AgentSession(
        # ... stt, llm, tts, etc.
    )


    avatar = keyframe.AvatarSession(
        persona_slug="public:cosmo_persona-1.5-live",  # or use persona_id. See "Persona setup" for details.
    )


    # Start the avatar and wait for it to join
    await avatar.start(session, room=ctx.room)


    # Start your agent session with the user
    await session.start(
        # ... room, agent, room_options, etc.
    )
```

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

### Installation (Node.js)

Source: https://docs.livekit.io/agents/models/llm/perplexity

Install the Perplexity plugin for Node.js using pnpm.

```APIDOC
## Installation (Node.js)

### Description
Install the Perplexity plugin for Node.js using pnpm.

### Command
```bash
pnpm add @livekit/agents-plugin-openai@1.x
```
```

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

### Install Gradium plugin with uv

Source: https://docs.livekit.io/agents/models/tts/plugins/gradium

Install the LiveKit Agents Gradium plugin from PyPI using uv.

```bash
uv add "livekit-agents[gradium]~=1.8"

```

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

### Plugin installation

Source: https://docs.livekit.io/agents/models/tts/inworld

Installation instructions for the Inworld plugin in Python and Node.js.

```APIDOC
## Plugin installation

### Description
Install the LiveKit Inworld plugin to use Inworld TTS.

### Method
N/A (package installation)

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
# Python (uv)
uv add "livekit-agents[inworld]~=1.8"
```

```bash
# Node.js (pnpm)
pnpm add @livekit/agents-plugin-inworld@1.x
```

### Response
No response body.
```

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

### Install Groq STT plugin (Python)

Source: https://docs.livekit.io/agents/models/stt/plugins/groq

Install the LiveKit Agents Groq plugin from PyPI using uv.

```bash
uv add "livekit-agents[groq]~=1.8"

```

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

### Install Fish Audio plugin (Python)

Source: https://docs.livekit.io/agents/models/tts/plugins/fishaudio

Install the LiveKit Fish Audio plugin for Python using uv.

```bash
uv add "livekit-agents[fishaudio]~=1.8"

```

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

### Node.js usage example

Source: https://docs.livekit.io/agents/models/avatar/plugins/bey

Example of using the Beyond Presence avatar in a Node.js AgentSession. It shows how to create an avatar session, start it, and start the agent session.

```javascript
import { voice } from '@livekit/agents';
import * as bey from '@livekit/agents-plugin-bey';


const session = new voice.AgentSession({
   // ... stt, llm, tts, etc.
});


const avatar = new bey.AvatarSession({
    avatarId: "...",  // ID of the Beyond Presence avatar to use
});


// Start the avatar and wait for it to join
await avatar.start(session, room);


// Start your agent session with the user
await session.start();
```

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

### Install the Synthesia plugin with uv

Source: https://docs.livekit.io/agents/models/avatar/plugins/synthesia

Install the plugin from PyPI using uv. The version specifier is ~=1.8.

```bash
uv add "livekit-agents[synthesia]~=1.8"
```

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

### Python usage example

Source: https://docs.livekit.io/agents/models/avatar/plugins/bey

Example of using the Beyond Presence avatar in a Python AgentSession. It shows how to create an avatar session, start it, and start the agent session.

```python
from livekit.plugins import bey


session = AgentSession(
   # ... stt, llm, tts, etc.
)


avatar = bey.AvatarSession(
    avatar_id="...",  # ID of the Beyond Presence avatar to use
)


# Start the avatar and wait for it to join
await avatar.start(session, room=ctx.room)


# Start your agent session with the user
await session.start(
    room=ctx.room,
)
```

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

### Install Python turn detector plugin

Source: https://docs.livekit.io/agents/logic/turns/turn-detector

Install the LiveKit Agents turn detector plugin from PyPI using uv.

```bash
uv add "livekit-agents[turn-detector]~=1.8"

```

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

### Install Soniox plugin (Python)

Source: https://docs.livekit.io/agents/models/stt/plugins/soniox

Install the Soniox STT plugin for Python using uv.

```bash
uv add "livekit-agents[soniox]~=1.8"

```

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

### Install Node.js dependencies with pnpm

Source: https://docs.livekit.io/agents/start/voice-ai-quickstart

Install the agent's runtime and plugin dependencies if you did not elect to have them automatically installed during template setup.

```bash
pnpm install
```

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

### Install Google plugin (Python)

Source: https://docs.livekit.io/agents/models/llm/gemini

Install the LiveKit Google plugin from PyPI using uv. The plugin is required for using Gemini with your own API key.

```bash
uv add "livekit-agents[google]~=1.8"

```

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

### Install Google plugin (Node.js)

Source: https://docs.livekit.io/agents/models/realtime/plugins/gemini

Install the LiveKit Agents Google plugin for Node.js using pnpm.

```bash
pnpm add "@livekit/agents-plugin-google@1.x"

```

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

### Install Inworld plugin (Python)

Source: https://docs.livekit.io/agents/models/tts/inworld

Install the Inworld plugin for Python using uv.

```bash
uv add "livekit-agents[inworld]~=1.8"

```

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

### Use TruGen avatar in AgentSession (Python and Node.js)

Source: https://docs.livekit.io/agents/models/avatar/plugins/trugen

Use the TruGen avatar in an AgentSession. The Python example uses trugen.AvatarSession and the Node.js example uses trugen.AvatarSession. Both start the avatar and wait for it to join before starting the agent session.

```python
from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import trugen


server = AgentServer()


@server.rtc_session()
async def my_agent(ctx: agents.JobContext):
   session = AgentSession(
      # ... stt, llm, tts, etc.
   )


   avatar = trugen.AvatarSession(
      avatar_id="...",  # ID of the TruGen stock avatar to use
   )


   # Start the avatar and wait for it to join
   await avatar.start(session, room=ctx.room)


   # Start your agent session with the user
   await session.start(
      # ... room, agent, room_options, etc....
   )
```

```typescript
import { voice } from '@livekit/agents';
import * as trugen from '@livekit/agents-plugin-trugen';


const session = new voice.AgentSession({
   // ... stt, llm, tts, etc.
});


const avatar = new trugen.AvatarSession({
   avatarId: '...',  // ID of the TruGen stock avatar to use
});


// Start the avatar and wait for it to join
await avatar.start(session, room);


// Start your agent session with the user
await session.start({
   // ... room, agent, room_options, etc.
});
```

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

### Use Runway AvatarSession in AgentSession (Python and Node.js)

Source: https://docs.livekit.io/agents/models/avatar/plugins/runway

Use the Runway avatar in an AgentSession. The avatar is started with the session and room, then the agent session is started. The Python example uses avatar_id, the Node.js example uses avatarId.

```python
from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import runway


server = AgentServer()


@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
    session = AgentSession(
        # ... stt, llm, tts, etc.
    )


    avatar = runway.AvatarSession(
        avatar_id="...",  # ID of the custom Runway character to use
    )


    # Start the avatar and wait for it to join
    await avatar.start(session, room=ctx.room)


    # Start your agent session with the user
    await session.start(
        # ... room, agent, room_options, etc....
    )
```

```javascript
import { voice } from '@livekit/agents';
import * as runway from '@livekit/agents-plugin-runway';


const session = new voice.AgentSession({
   // ... stt, llm, tts, etc.
});


const avatar = new runway.AvatarSession({
   avatarId: '...',  // ID of the custom Runway character to use
});


// Start the avatar and wait for it to join
await avatar.start(session, room);


// Start your agent session with the user
await session.start({
   // ... room, agent, room_options, etc.
});
```

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

### Install Groq plugin for Python

Source: https://docs.livekit.io/agents/models/llm/groq

Install the required package for using the Groq plugin in a Python environment.

```bash
uv add "livekit-agents[groq]~=1.8"
```

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

### Initialize uv project

Source: https://docs.livekit.io/agents/integrations/google

Initializes a new uv project named livekit-gemini-agent and changes into its directory.

```bash
uv init livekit-gemini-agent --bare
cd livekit-gemini-agent

```

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

### Install MiniMax TTS plugin

Source: https://docs.livekit.io/agents/models/tts/minimax

Install the MiniMax TTS plugin for LiveKit Agents from PyPI.

```bash
pip install "livekit-agents[minimax]~=1.8"
```

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

### Install the Python plugin

Source: https://docs.livekit.io/agents/models/llm/plugins/cerebras

Install the LiveKit Agents Cerebras plugin for Python using uv.

```bash
uv add "livekit-agents[cerebras]~=1.8"
```

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

### Start a simple single-agent session in Python

Source: https://docs.livekit.io/agents/logic/sessions

Creates an AgentSession with STT, LLM, TTS, and turn detection, then starts it with a room, an agent, and room options including noise cancellation. Uses the livekit.agents and livekit.plugins modules.

```python
from livekit.agents import AgentSession, Agent, inference, room_io, TurnHandlingOptions
from livekit.plugins import noise_cancellation


session = AgentSession(
    stt="assemblyai/universal-3-5-pro:en",
    llm="google/gemma-4-31b-it",
    tts="fishaudio/s2.1-pro:fa4c9eb3dccc4806b382b40d61c6b10a",
    turn_handling=TurnHandlingOptions(
        turn_detection=inference.TurnDetector(),
    ),
)


await session.start(
    room=ctx.room,
    agent=Agent(instructions="You are a helpful voice AI assistant."),
    room_options=room_io.RoomOptions(
        audio_input=room_io.AudioInputOptions(
            noise_cancellation=noise_cancellation.BVC(),
        ),
    ),
)

```

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

### Add Anam virtual avatar to AgentSession

Source: https://docs.livekit.io/agents/models/avatar

Example using the Anam plugin to add a virtual avatar to an AgentSession. Install the plugin and API keys first, then create an AgentSession, an AvatarSession, start the avatar with the session and room, wait for the avatar to join, and start the agent session with audio output disabled. wait_for_join() waits up to 30 seconds by default and raises asyncio.TimeoutError if the avatar doesn't join in time; pass timeout=None to wait indefinitely.

```python
from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import anam


server = AgentServer()


@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
   session = AgentSession(
      # ... stt, llm, tts, etc.
   )


   avatar = anam.AvatarSession(
      persona_config=anam.PersonaConfig(
         name="...",  # Name of the avatar to use.
         avatarId="...",  # ID of the avatar to use.
      ),
   )


   # Start the avatar
   await avatar.start(session, room=ctx.room)


   # Wait for the avatar to join and publish its video track
   await avatar.wait_for_join()


   # Start your agent session with the user
   await session.start(
      # ... room, agent, room_options, etc....
   )

```

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

### Add thinking sound with BackgroundAudioPlayer (Python and Node.js)

Source: https://docs.livekit.io/agents/build/external-data

Configure a background audio player to play a 'thinking' sound while tool calls are ongoing. The Python example uses BackgroundAudioPlayer with thinking_sound and BuiltinAudioClip.KEYBOARD_TYPING clips; the Node.js example uses voice.BackgroundAudioPlayer with thinkingSound and probability weights. Both start the player after the agent session starts.

```python
from livekit.agents import AgentServer, BackgroundAudioPlayer, AudioConfig, BuiltinAudioClip


server = AgentServer()


@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
    session = AgentSession(
        # ... stt, llm, tts, vad, turn_detection, etc.
    )


    await session.start(
        room=ctx.room,
        # ... agent, etc.
    )


    background_audio = BackgroundAudioPlayer(
        thinking_sound=[
            AudioConfig(BuiltinAudioClip.KEYBOARD_TYPING, volume=0.8),
            AudioConfig(BuiltinAudioClip.KEYBOARD_TYPING2, volume=0.7),
        ],
    )
    await background_audio.start(room=ctx.room, agent_session=session)

```

```typescript
import { type JobContext, defineAgent, log, voice } from '@livekit/agents';




export default defineAgent({
  entry: async (ctx: JobContext) => {
    const logger = log();


    await ctx.connect();
    logger.info('Connected to room');


    const agent = voice.Agent.create({
      instructions: 'You are a helpful assistant',
      // ... tools, etc.
    });


    const session = new voice.AgentSession({
      // ... stt, llm, tts, vad, turn_detection, etc.
    });
    await session.start({ agent, room: ctx.room });


    const backgroundAudio = new voice.BackgroundAudioPlayer({
      thinkingSound: [
        { source: voice.BuiltinAudioClip.KEYBOARD_TYPING, volume: 0.8, probability: 0.6 },
        { source: voice.BuiltinAudioClip.KEYBOARD_TYPING2, volume: 0.7, probability: 0.4 },
      ],
    });


    await backgroundAudio.start({ room: ctx.room, agentSession: session });


    // Play another audio file at any time using the play method:
    // backgroundAudio.play('filepath.ogg');
  },
});

```

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

### AssemblyAI session started log

Source: https://docs.livekit.io/agents/models/stt/assemblyai

Example of the automatic INFO-level log line that includes the session ID and expiry timestamp. The session ID is logged automatically when the session starts.

```text
AssemblyAI session started id=676d673c-83fc-4d8a-bd95-bfe23b1c5a50 expires_at=1773775624
```

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

### Install AWS plugin with realtime extra

Source: https://docs.livekit.io/agents/models/realtime/plugins/nova-sonic

Install the AWS plugin from PyPI with the realtime extra using uv.

```bash
uv add "livekit-plugins-aws[realtime]"
```

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

### Install Mistral TTS plugin (Python)

Source: https://docs.livekit.io/agents/models/tts/mistralai

Install the LiveKit Mistral AI plugin from PyPI using uv.

```bash
uv add "livekit-agents[mistralai]~=1.8"
```

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

### xai.STT

Source: https://docs.livekit.io/agents/models/stt/plugins/spacexai

Documentation for the SpaceXAI STT plugin constructor, including installation, authentication, and usage examples.

```APIDOC
## [STT] xai.STT

### Description
Creates a SpaceXAI STT instance for use in an AgentSession or as a standalone transcription service.

### Method
Constructor

### Endpoint
N/A (SDK constructor)

### Parameters
- **api_key** (string) - Required - SpaceXAI API key. Env: `XAI_API_KEY`.
- **language** (string) - Optional - BCP-47 language code for transcription (e.g., `"en"`, `"fr"`, `"de"`). Default: `en`.
- **enable_interim_results** (bool) - Optional - Whether to return in-progress transcription results before the final transcript. Disable to reduce the number of messages at the cost of higher latency. Default: `True`. In Node.js this parameter is called `interimResults`.
- **enable_diarization** (bool) - Optional - Set to `True` to enable speaker diarization. Default: `False`. In Node.js this parameter is called `enableDiarization`.

### Request Example
```python
from livekit.plugins import xai

session = AgentSession(
    stt=xai.STT(
        language="en",
    ),
    # ... llm, tts, etc.
)
```

### Response
No direct response; the STT instance is used within an AgentSession or as a standalone transcription service.
```

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

### Initialize agent with Node.js template

Source: https://docs.livekit.io/agents/start/voice-ai-quickstart

Run this command to create a new agent project using the Node.js starter template. The CLI clones the template into the 'my-agent' directory and creates an '.env.local' file with your LiveKit credentials.

```bash
lk agent init my-agent --template agent-starter-node
```

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

### Use D-ID avatar in AgentSession (Node.js)

Source: https://docs.livekit.io/agents/models/avatar/plugins/did

Node.js example showing how to create a D-ID AvatarSession, start it with the room, and then start the AgentSession. Requires a D-ID API key set as DID_API_KEY and an existing agent ID.

```typescript
import { voice } from '@livekit/agents';
import * as did from '@livekit/agents-plugin-did';


const session = new voice.AgentSession({
   // ... stt, llm, tts, etc.
});


const avatar = new did.AvatarSession({
   agentId: "...",  // ID of the D-ID avatar to use. See "Avatar setup" for details.
});


// Start the avatar and wait for it to join
await avatar.start(session, room);


// Start your agent session with the user
await session.start(
   // ... room, agent, room_options, etc.
);
```

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

### Use D-ID avatar in AgentSession (Python)

Source: https://docs.livekit.io/agents/models/avatar/plugins/did

Python example showing how to create a D-ID AvatarSession, start it with the room, and then start the AgentSession. Requires a D-ID API key set as DID_API_KEY and an existing agent ID.

```python
from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import did


server = AgentServer()


@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
   session = AgentSession(
      # ... stt, llm, tts, etc.
   )


   avatar = did.AvatarSession(
      agent_id="...",  # ID of the D-ID avatar to use. See "Avatar setup" for details.
   )


   # Start the avatar and wait for it to join
   await avatar.start(session, room=ctx.room)


   # Start your agent session with the user
   await session.start(
      # ... room, agent, room_options, etc....
   )
```

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

### Initialize agent with Python template

Source: https://docs.livekit.io/agents/start/voice-ai-quickstart

Run this command to create a new agent project using the Python starter template. The CLI clones the template into the 'my-agent' directory and creates an '.env.local' file with your LiveKit credentials.

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

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

### Use Phonic RealtimeModel in AgentSession (Python and Node.js)

Source: https://docs.livekit.io/agents/models/realtime/plugins/phonic

Use Phonic in an AgentSession, for example in the Voice AI quickstart. Both Python and Node.js examples create an AgentSession with a Phonic RealtimeModel using the voice "sabrina".

```python
from livekit.plugins import phonic


session = AgentSession(
   llm=phonic.realtime.RealtimeModel(voice="sabrina"),
)
```

```typescript
import * as phonic from '@livekit/agents-plugin-phonic';


const session = new voice.AgentSession({
   llm: new phonic.realtime.RealtimeModel({ voice: "sabrina" }),
});
```

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

### Use the Synthesia plugin in an AgentSession

Source: https://docs.livekit.io/agents/models/avatar/plugins/synthesia

Example of using the Synthesia plugin in an AgentSession. It creates an AvatarSession with an AvatarConfig containing avatar IDs, starts the avatar, and then starts the session. The avatar IDs are placeholders and must be replaced with valid ones.

```python
from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import synthesia


server = AgentServer()


@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
    session = AgentSession(
        # ... stt, llm, tts, etc.
    )


    avatar = synthesia.AvatarSession(
        synthesia.AvatarConfig(
            # IDs of the Synthesia avatars to use. See "Avatar setup" for details.
            avatar_ids=[
                "03cee7ec-ac90-45ec-8c20-74a399cf3dc4",
                "2d1e1b5f-8ce0-4c3f-b0d3-9c4a1a6e5f77",
            ],
        ),
    )


    # Start the avatar and wait for it to join
    await avatar.start(session, room=ctx.room)


    # Start your agent session with the user
    await session.start(
        # ... room, agent, room_options, etc.
    )
```

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

### Install the Gnani STT plugin with uv

Source: https://docs.livekit.io/agents/models/stt/gnani

Install the plugin from PyPI using uv. Run this in your project directory.

```bash
uv add "livekit-agents[gnani]~=1.8"
```

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

### Start agent in dev mode: lk agent dev

Source: https://docs.livekit.io/agents/server/startup-modes

Starts the agent server in development mode with debug logging and auto-reload enabled. Use this for local development to get detailed logs and automatic code reloading on changes.

```bash
lk agent dev

```

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

### Use AvatarSession in an AgentSession

Source: https://docs.livekit.io/agents/models/avatar/plugins/avatartalk

Example of using the AvatarTalk plugin in an AgentSession. It creates an AvatarSession with an avatar ID and starts it with the agent session.

```python
from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import avatartalk


server = AgentServer()


@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
   session = AgentSession(
      # ... stt, llm, tts, etc.
   )


   avatar = avatartalk.AvatarSession(
      avatar="...",  # ID of the AvatarTalk avatar to use. See "Avatar setup" for details.
   )


   # Start the avatar and wait for it to join
   await avatar.start(session, room=ctx.room)


   # Start your agent session with the user
   await session.start(
      # ... room, agent, room_options, etc....
   )
```

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

### Use Anam avatar in AgentSession (Node.js)

Source: https://docs.livekit.io/agents/models/avatar/plugins/anam

Node.js example showing how to create an Anam AvatarSession and start it with an AgentSession. Requires ANAM_API_KEY in .env.

```typescript
import { voice } from '@livekit/agents';
import * as anam from '@livekit/agents-plugin-anam';


const session = new voice.AgentSession({
   // ... stt, llm, tts, etc.
});


const avatar = new anam.AvatarSession({
   personaConfig: {
      name: "...",  // Name of the avatar to use.
      avatarId: "...",  // ID of the avatar to use. See "Avatar setup" for details.
   },
});


// Start the avatar and wait for it to join
await avatar.start(session, room);


// Start your agent session with the user
await session.start(
   // ... room, agent, room_options, etc.
);
```

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

### Use Anam avatar in AgentSession (Python)

Source: https://docs.livekit.io/agents/models/avatar/plugins/anam

Python example showing how to create an Anam AvatarSession and start it with an AgentSession. Requires ANAM_API_KEY in .env.

```python
from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import anam


server = AgentServer()


@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
   session = AgentSession(
      # ... stt, llm, tts, etc.
   )


   avatar = anam.AvatarSession(
      persona_config=anam.PersonaConfig(
         name="...",  # Name of the avatar to use.
         avatarId="...",  # ID of the avatar to use. See "Avatar setup" for details.
      ),
   )


   # Start the avatar and wait for it to join
   await avatar.start(session, room=ctx.room)


   # Start your agent session with the user
   await session.start(
      # ... room, agent, room_options, etc....
   )
```

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

### Install Google STT plugin with uv

Source: https://docs.livekit.io/agents/models/stt/google

Install the LiveKit Agents Google plugin from PyPI using uv. Use this command in your project environment.

```bash
uv add "livekit-agents[google]~=1.8"
```

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

### Set log level via environment variable

Source: https://docs.livekit.io/agents/server/options

Set the log level via environment variable when starting the agent server directly. The Python example uses LIVEKIT_LOG_LEVEL, while the Node.js example uses LOG_LEVEL. The agent reads the variable at startup from your terminal or a Dockerfile.

```bash
LIVEKIT_LOG_LEVEL=debug uv run src/agent.py start
```

```bash
LOG_LEVEL=debug node dist/main.js start
```

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

### Create Telnyx LLM with with_telnyx

Source: https://docs.livekit.io/agents/models/llm/telnyx

Create a Telnyx LLM using the with_telnyx method (Python) or withTelnyx (Node.js). Both examples show the same setup with the default model.

```python
from livekit.plugins import openai


session = AgentSession(
    llm=openai.LLM.with_telnyx(
        model="meta-llama/Meta-Llama-3.1-70B-Instruct",
    ),
    # ... tts, stt, vad, turn_handling, etc.
)
```

```typescript
import * as openai from '@livekit/agents-plugin-openai';


const session = new voice.AgentSession({
    llm: openai.LLM.withTelnyx({
        model: "meta-llama/Meta-Llama-3.1-70B-Instruct",
    }),
    // ... tts, stt, vad, turnHandling, etc.
});
```

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

### Install livekit-agents[avatario] with uv

Source: https://docs.livekit.io/agents/models/avatar/plugins/avatario

Install the Avatario plugin for LiveKit Agents from PyPI using uv.

```bash
uv add "livekit-agents[avatario]~=1.8"
```

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

### Entrypoint example processing audio tracks (Python)

Source: https://docs.livekit.io/agents/server/job

Defines an entrypoint that sets up a room listener for subscribed audio tracks, connects with audio-only auto-subscribe, sends a text message, and iterates remote participants.

```python
async def do_something(track: rtc.RemoteAudioTrack):
    audio_stream = rtc.AudioStream(track)
    async for event in audio_stream:
        # Do something here to process event.frame
        pass
    await audio_stream.aclose()


@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: JobContext):
    # an rtc.Room instance from the LiveKit Python SDK
    room = ctx.room


    # set up listeners on the room before connecting
    @room.on("track_subscribed")
    def on_track_subscribed(track: rtc.Track, *_):
        if track.kind == rtc.TrackKind.KIND_AUDIO:
            asyncio.create_task(do_something(track))


    # connect to room
    await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)


    # when connected, room.local_participant represents the agent
    await room.local_participant.send_text('hello world', topic='hello-world')


    # iterate through currently connected remote participants
    for rp in room.remote_participants.values():
        print(rp.identity)

```

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

### Filter MCP tools with MCPToolset.filter_tools()

Source: https://docs.livekit.io/agents/logic/tools/mcp

Use MCPToolset.filter_tools() for more control. It accepts a predicate function and filters tools in-place after setup. This example creates an MCPToolset, manually calls setup() to connect and fetch tools, then calls filter_tools() with a lambda that only keeps tools with IDs containing "search".

```python
from livekit.agents import mcp


toolset = mcp.MCPToolset(
    id="my-api",
    mcp_server=mcp.MCPServerHTTP("https://your-mcp-server.com/mcp"),
)


# When using outside of AgentSession, call setup() manually
await toolset.setup()
toolset.filter_tools(lambda tool: "search" in tool.id)

```

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

### Python: Configure room options with noise cancellation

Source: https://docs.livekit.io/agents/logic/sessions

Use this Python example to configure room options for a LiveKit agent session, including video input, noise cancellation, and transcription sync. The example creates a RoomOptions object and passes it to session.start().

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




room_options=room_io.RoomOptions(
    video_input=True,
    audio_input=room_io.AudioInputOptions(
        noise_cancellation=noise_cancellation.BVC(),
    ),
    text_output=room_io.TextOutputOptions(
        sync_transcription=False,
    ),
    participant_identity="user_123",
)


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

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

### Swap avatars with swap_avatar

Source: https://docs.livekit.io/agents/models/avatar/plugins/synthesia

Example of swapping avatars on a started session. The first call swaps to a specific avatar ID, the second returns to the default (first ID). The method returns the active avatar ID.

```python
await avatar.swap_avatar("2d1e1b5f-8ce0-4c3f-b0d3-9c4a1a6e5f77")
await avatar.swap_avatar("default")  # back to the first ID
```

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

### Use AsyncAI TTS in AgentSession

Source: https://docs.livekit.io/agents/models/tts/asyncai

Use AsyncAI TTS within an AgentSession. The model parameter defaults to "async_flash_v1.0" and can be omitted. This example shows the minimal setup for integrating AsyncAI TTS into a voice agent.

```python
from livekit.plugins import asyncai


session = AgentSession(
   tts=asyncai.TTS(
      model="async_flash_v1.0",
   )
   # ... llm, stt, etc.
)
```

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

### Install Protoface plugin with uv (Python)

Source: https://docs.livekit.io/agents/models/avatar/plugins/protoface

Install the Protoface plugin for Python using uv. Requires Python and the livekit-agents package.

```bash
uv add "livekit-agents[protoface]~=1.8"
```

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

### Configure AgentSession with LiveKit Inference modules

Source: https://docs.livekit.io/agents/models/inference

Configure an AgentSession with LiveKit Inference STT, LLM, and TTS modules. The Python and Node.js examples are equivalent renderings of the same setup, using the 'inference' module classes with model and voice identifiers.

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


session = AgentSession(
    stt=inference.STT(
        model="deepgram/flux-general",
        language="en"
    ),
    llm=inference.LLM(
        model="google/gemma-4-31b-it",
    ),
    tts=inference.TTS(
        model="fishaudio/s2.1-pro",
        voice="fa4c9eb3dccc4806b382b40d61c6b10a",
    ),
)

```

```javascript
import { AgentSession, inference } from '@livekit/agents';


const session = new AgentSession({
    stt: new inference.STT({
        model: "deepgram/flux-general",
        language: "en"
    }),
    llm: new inference.LLM({
        model: "google/gemma-4-31b-it",
    }),
    tts: new inference.TTS({
        model: "fishaudio/s2.1-pro",
        voice: "fa4c9eb3dccc4806b382b40d61c6b10a",
    }),
});

```

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

### Start a simple single-agent session in Node.js

Source: https://docs.livekit.io/agents/logic/sessions

Creates an AgentSession with STT, LLM, TTS, and turn detection, then starts it with a room, an agent, and input options including noise cancellation. Uses the @livekit/agents and @livekit/noise-cancellation-node modules.

```javascript
import { voice, inference } from '@livekit/agents';
import { BackgroundVoiceCancellation } from '@livekit/noise-cancellation-node';


const session = new voice.AgentSession({
  stt: "assemblyai/universal-3-5-pro:en",
  llm: "google/gemma-4-31b-it",
  tts: "fishaudio/s2.1-pro:fa4c9eb3dccc4806b382b40d61c6b10a",
  turnHandling: {
    turnDetection: new inference.TurnDetector(),
  },
});


await session.start({
  room: ctx.room,
  agent: voice.Agent.create({
    instructions: "You are a helpful voice AI assistant.",
  }),
  inputOptions: {
    noiseCancellation: BackgroundVoiceCancellation(),
  },
});

```

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

### Toggle audio input and output dynamically (Node.js)

Source: https://docs.livekit.io/agents/build/text

For hybrid sessions where audio may be toggled, use session.input.setAudioEnabled() and session.output.setAudioEnabled(). This still publishes the audio track to the room. The example starts with audio disabled, then toggles it via an RPC method 'toggle_audio'.

```javascript
import { voice } from '@livekit/agents';


const session = new voice.AgentSession({
  // ... configuration
});


// start with audio disabled
session.input.setAudioEnabled(false);
session.output.setAudioEnabled(false);
await session.start({
  agent,
  room: ctx.room,
});


// user toggles audio switch
ctx.room.localParticipant.registerRpcMethod('toggle_audio', async (data) => {
  session.input.setAudioEnabled(!session.input.audioEnabled);
  session.output.setAudioEnabled(!session.output.audioEnabled);
});
```

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

### Install Fish Audio plugin (Node.js)

Source: https://docs.livekit.io/agents/models/tts/plugins/fishaudio

Install the LiveKit Fish Audio plugin for Node.js using pnpm.

```bash
pnpm add @livekit/agents-plugin-fishaudio@1.x

```
Tokens:
Raw