LiveKit docs › Build Agents › Get Started › Voice AI quickstart

---

# Voice AI quickstart

> Build and deploy a simple voice assistant in less than 10 minutes.

## Overview

This guide walks you through the setup of your very first voice assistant using LiveKit Agents. In less than 10 minutes, you'll have a voice assistant that you can speak to in your terminal, browser, telephone, or native app.

> 💡 **LiveKit Agent Builder**
> 
> The LiveKit Agent Builder is a quick way to get started with voice agents in your browser, without writing any code. It's perfect for prototyping and exploring ideas, but doesn't have as many features as the full LiveKit Agents SDK. See the [Agent Builder](https://docs.livekit.io/agents/start/builder.md) guide for more details.

### Coding agent support

LiveKit is built for coding agents like [Claude Code](https://claude.com/product/claude-code), [Cursor](https://www.cursor.com/), and [Codex](https://openai.com/codex/). These agents can build agents and frontends with the LiveKit SDKs and manage resources with the [LiveKit CLI](https://docs.livekit.io/reference/developer-tools/livekit-cli.md#install-the-cli). Give your agent LiveKit expertise with [Agent Skills](https://docs.livekit.io/intro/coding-agents.md#agent-skills) and the Docs MCP server, and let it try its changes with the [CLI agent debugger](https://docs.livekit.io/testing/debugger.md). Install the skills and the MCP server for all of your coding agents with one command:

```shell
lk skills install

```

Run it in your project directory, or add `--global` to install for all projects. For Claude Code, you can install the LiveKit plugin instead. For more information, see the [coding agents guide](https://docs.livekit.io/intro/coding-agents.md).

## Starter projects

The simplest way to get your first agent running is with one of the following starter projects. You can create a project from a template with the CLI (see [Quick start with CLI](#setup-with-cli)) or click "Use this template" on GitHub and follow the project's README.

These projects are constructed with best practices, a complete working agent, tests, and an AGENTS.md optimized to turn coding agents like [Claude Code](https://claude.com/product/claude-code) and [Cursor](https://www.cursor.com/) into LiveKit experts.

- **[Python starter project](https://github.com/livekit-examples/agent-starter-python)**: Ready-to-go Python starter project. Clone a repo with all the code you need to get started.

- **[Node.js starter project](https://github.com/livekit-examples/agent-starter-node)**: Ready-to-go Node.js starter project. Clone a repo with all the code you need to get started.

## Requirements

The following sections describe the minimum requirements to get started with LiveKit Agents.

**Python**:

- LiveKit Agents requires Python >= 3.10.
- This guide uses the [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager.

---

**Node.js**:

- LiveKit Agents for Node.js requires Node.js >= 20.
- This guide uses [pnpm](https://pnpm.io/installation) package manager and requires pnpm >= 10.15.0.

### LiveKit Cloud

This guide assumes you have signed up for a free [LiveKit Cloud](https://cloud.livekit.io/) account. LiveKit Cloud includes agent deployment, model inference, and realtime media transport. Create a free project and use the API keys in the following steps to get started.

While this guide assumes LiveKit Cloud, the instructions can be adapted for [self-hosting](https://docs.livekit.io/transport/self-hosting/local.md) the open source LiveKit server instead. For self-hosting in production, set up a [custom deployment](https://docs.livekit.io/deploy/custom/deployments.md) environment, and make the following changes: remove the [enhanced noise cancellation](https://docs.livekit.io/transport/media/noise-cancellation.md) plugin from the agent code, and use [plugins](https://docs.livekit.io/agents/models.md#plugins) for your own AI providers.

### LiveKit CLI

Use the LiveKit CLI to manage LiveKit API keys and deploy your agent to LiveKit Cloud.

1. Install the LiveKit CLI:

**macOS**:

Install the LiveKit CLI with [Homebrew](https://brew.sh/):

```text
brew install livekit-cli

```

---

**Linux**:

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

```

> 💡 **Tip**
> 
> You can also download the latest precompiled binaries [here](https://github.com/livekit/livekit-cli/releases/latest).

---

**Windows**:

```text
winget install LiveKit.LiveKitCLI

```

> 💡 **Tip**
> 
> You can also download the latest precompiled binaries [here](https://github.com/livekit/livekit-cli/releases/latest).

---

**From Source**:

This repo uses [Git LFS](https://git-lfs.github.com/) for embedded video resources. Please ensure git-lfs is installed on your machine before proceeding.

```text
git clone github.com/livekit/livekit-cli
make install

```
2. Link your LiveKit Cloud project to the CLI:

```shell
lk cloud auth

```

This opens a browser window to authenticate and link your project to the CLI.

## Quickstart steps

The following sections walk you through the steps to get your first agent running.

### Setup with CLI

The simplest way to get your first agent running is with the LiveKit CLI.

Make sure your project meets all [requirements](#requirements), then run:

**Python**:

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

```

---

**Node.js**:

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

```

The CLI clones the template into the `my-agent` directory, creates an `.env.local` file with your LiveKit credentials, and prints the next steps to run your agent.

> 💡 **Save the chat link**
> 
> Open the link provided by the CLI after the line `"To try your new agent in the web console, visit:"` to speak to your agent in the following step.

Follow the instructions it prints, which guide you through the following steps:

1. **Select a project to use** — If you don't have a default project set, the CLI prompts you to select a project to use.
2. **Change into the project directory** — The project directory is named after your agent.

```shell
cd my-agent

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

**Python**:

```shell
uv sync

```

---

**Node.js**:

```shell
pnpm install

```
4. **Run your agent** — Run your agent in development mode.

```shell
lk agent dev

```

### Speak to your agent

If you opened the Console link provided by the CLI in the previous step, return to your browser and click **Start a session**. Otherwise, you can always find the Console on your project's [Agents dashboard](https://cloud.livekit.io/projects/p_/agents). Use the microphone button to speak to your agent and see its responses in real time, and explore the tool panes to measure your agent's behavior and performance in detail.

## Other options

You can customize your agent by choosing different AI models and by exploring testing and deployment options.

### AI models

Voice agents require one or more [AI models](https://docs.livekit.io/agents/models.md) to provide understanding, intelligence, and speech. LiveKit Agents supports both high-performance STT-LLM-TTS voice pipelines constructed from multiple specialized models, as well as realtime models with direct speech-to-speech capabilities. For help deciding which pipeline fits your use case, see [Pipeline types](https://docs.livekit.io/agents/models/pipelines.md).

**STT-LLM-TTS pipeline**:

Your agent strings together three specialized providers through LiveKit Inference into a high-performance voice pipeline. No additional setup is required.

![Diagram showing STT-LLM-TTS pipeline.](/images/agents/stt-llm-tts-pipeline.svg)

| Component | Model | Alternatives |
| STT | AssemblyAI Universal-3.6 Pro | [STT models](https://docs.livekit.io/agents/models/stt.md) |
| LLM | Gemma 4 31B | [LLM models](https://docs.livekit.io/agents/models/llm.md) |
| TTS | Fish Audio S2.1 Pro | [TTS models](https://docs.livekit.io/agents/models/tts.md) |

---

**Realtime model**:

Your agent uses a single realtime model through LiveKit Inference to provide an expressive and lifelike voice experience. You don't need any additional setup.

![Diagram showing realtime model.](/images/agents/realtime-model.svg)

| Model | Alternatives |
| [OpenAI GPT Realtime 2.1](https://docs.livekit.io/agents/models/realtime/openai.md) | [Realtime models](https://docs.livekit.io/agents/models/realtime.md) |

You can change the AI models used by editing your agent file. Full agent files for STT-LLM-TTS and Realtime models can be found in the [Agent code](#agent-code) section.

### Test and deploy

Use different modes and deployment options to test and deploy your agent.

#### Server startup modes

Start your agent server in development or production modes.

- `console` mode: Run your agent locally in your terminal.
- `dev` mode: Run your agent in development mode for testing and debugging.
- `start` mode: Run your agent in production mode.

To learn more about these modes, see the [Server startup modes](https://docs.livekit.io/agents/server/startup-modes/) reference.

To run your agent in production mode:

```shell
lk agent start

```

#### Connect to Agent Console

Start your agent in `dev` mode to connect it to LiveKit and make it available from anywhere on the internet:

```shell
lk agent dev

```

Use the [Agent Console](https://docs.livekit.io/testing/agent-console.md) to interact with and debug your agent in realtime. Note that you'll need to set the **Agent name**, which should be `my-agent` for this quickstart.

#### Deploy to LiveKit Cloud

Run `lk agent create` from the project directory to register and deploy.

After the deployment completes, you can access your agent in the [Agent Console](https://docs.livekit.io/testing/agent-console.md), or continue to use [console mode](https://docs.livekit.io/agents/server/startup-modes.md#console-mode) as you build and test your agent locally.

## Agent code

Once you have the quickstart running, you can dig into the agent code. For the difference between realtime and chained (STT-LLM-TTS) pipelines, see [AI models](#ai-models). The tabs below show the full files for each pipeline type so you can swap, copy, or adapt them.

**STT-LLM-TTS pipeline**:

** Filename: `agent.py`**

```python
from dotenv import load_dotenv

from livekit import agents
from livekit.agents import AgentServer, AgentSession, Agent, inference, room_io, TurnHandlingOptions
from livekit.plugins import ai_coustics

load_dotenv(".env.local")


class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="""You are a helpful voice AI assistant.
            You eagerly assist users with their questions by providing information from your extensive knowledge.
            Your responses are concise, to the point, and without any complex formatting or punctuation including emojis, asterisks, or other symbols.
            You are curious, friendly, and have a sense of humor.""",
        )

server = AgentServer()

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
    session = AgentSession(
        stt=inference.STT(model="assemblyai/universal-3-6-pro", language="en"),
        llm=inference.LLM(model="google/gemma-4-31b-it"),
        tts=inference.TTS(
            model="fishaudio/s2.1-pro",
            voice="fa4c9eb3dccc4806b382b40d61c6b10a",
        ),
        turn_handling=TurnHandlingOptions(
            turn_detection=inference.TurnDetector(),
        ),
    )

    await session.start(
        room=ctx.room,
        agent=Assistant(),
        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.generate_reply(
        instructions="Greet the user and offer your assistance."
    )


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


```

** Filename: `main.ts`**

```typescript
import {
  type JobContext,
  ServerOptions,
  cli,
  defineAgent,
  inference,
  voice,
} from '@livekit/agents';
import * as aiCoustics from '@livekit/plugins-ai-coustics';
import { fileURLToPath } from 'node:url';
import dotenv from 'dotenv';
import { createAgent } from './agent';

dotenv.config({ path: '.env.local' });

export default defineAgent({
  entry: async (ctx: JobContext) => {
    const session = new voice.AgentSession({
      stt: new inference.STT({ model: 'assemblyai/universal-3-6-pro', language: 'en' }),
      llm: new inference.LLM({ model: 'google/gemma-4-31b-it' }),
      tts: new inference.TTS({
        model: 'fishaudio/s2.1-pro',
        voice: 'fa4c9eb3dccc4806b382b40d61c6b10a',
      }),
      turnHandling: {
        turnDetection: new inference.TurnDetector(),
      },
    });

    await session.start({
      agent: createAgent(),
      room: ctx.room,
      inputOptions: {
        noiseCancellation: aiCoustics.audioEnhancement({ model: aiCoustics.EnhancerModel.QuailVfS }),
      },
    });

    await ctx.connect();

    const handle = session.generateReply({
      instructions: 'Greet the user and offer your assistance.',
    });
  },
});

cli.runApp(new ServerOptions({ agent: fileURLToPath(import.meta.url), agentName: 'my-agent' }));

```

** Filename: `agent.ts`**

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

export function createAgent() {
  return voice.Agent.create({
    instructions: `You are a helpful voice AI assistant.
      You eagerly assist users with their questions by providing information from your extensive knowledge.
      Your responses are concise, to the point, and without any complex formatting or punctuation including emojis, asterisks, or other symbols.
      You are curious, friendly, and have a sense of humor.`,
  });
}

```

---

**Realtime model**:

** Filename: `agent.py`**

```python
from dotenv import load_dotenv

from livekit import agents
from livekit.agents import AgentServer, AgentSession, Agent, inference, room_io
from livekit.plugins import ai_coustics

load_dotenv(".env.local")

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(instructions="You are a helpful voice AI assistant.")

server = AgentServer()

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
    session = AgentSession(
        llm=inference.RealtimeModel(
            model="openai/gpt-realtime-2.1",
            voice="marin",
        )
    )

    await session.start(
        room=ctx.room,
        agent=Assistant(),
        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.generate_reply(
        instructions="Greet the user and offer your assistance. You should start by speaking in English."
    )


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


```

** Filename: `main.ts`**

```typescript
import {
  type JobContext,
  ServerOptions,
  cli,
  defineAgent,
  inference,
  voice,
} from '@livekit/agents';
import * as aiCoustics from '@livekit/plugins-ai-coustics';
import { fileURLToPath } from 'node:url';
import dotenv from 'dotenv';
import { createAgent } from './agent';

dotenv.config({ path: '.env.local' });

export default defineAgent({
  entry: async (ctx: JobContext) => {
    const session = new voice.AgentSession({
      llm: new inference.RealtimeModel({
        model: 'openai/gpt-realtime-2.1',
        voice: 'marin',
      }),
    });

    await session.start({
      agent: createAgent(),
      room: ctx.room,
      inputOptions: {
        noiseCancellation: aiCoustics.audioEnhancement({ model: aiCoustics.EnhancerModel.QuailVfS }),
      },
    });

    await ctx.connect();

    await session.generateReply({
      instructions: 'Greet the user and offer your assistance. You should start by speaking in English.',
    });
  },
});

cli.runApp(new ServerOptions({ agent: fileURLToPath(import.meta.url), agentName: 'my-agent' }));

```

** Filename: `agent.ts`**

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

export function createAgent() {
  return voice.Agent.create({
    instructions: 'You are a helpful voice AI assistant.',
  });
}

```

## Next steps

Follow these guides to bring your voice AI app to life in the real world.

- **[Web and mobile frontends](https://docs.livekit.io/agents/start/frontend.md)**: Put your agent in your pocket with a custom web or mobile app.

- **[Telephony integration](https://docs.livekit.io/agents/start/telephony.md)**: Your agent can place and receive calls with LiveKit's SIP integration.

- **[Testing your agent](https://docs.livekit.io/testing.md)**: Add behavioral tests to fine-tune your agent's behavior.

- **[Building voice agents](https://docs.livekit.io/agents/build.md)**: Comprehensive documentation to build advanced voice AI apps with LiveKit.

- **[Agent server](https://docs.livekit.io/agents/server.md)**: Learn how to manage your agents with agent servers and jobs.

- **[Deploying to LiveKit Cloud](https://docs.livekit.io/agents/ops/deployment.md)**: Learn more about deploying and scaling your agent in production.

- **[AI Models](https://docs.livekit.io/agents/models.md)**: Explore the full list of AI models available with LiveKit Agents.

- **[Recipes](https://docs.livekit.io/reference/recipes.md)**: A comprehensive collection of examples, guides, and recipes for LiveKit Agents.

---

This document was rendered at 2026-10-27T05:23:49.035Z.
For the latest version of this document, see [https://docs.livekit.io/agents/start/voice-ai.md](https://docs.livekit.io/agents/start/voice-ai.md).

To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).