LiveKit Agents starter for Node.js

A starter project for building voice AI apps with LiveKit Agents for Node.js and LiveKit Cloud.

The starter includes:

• A simple voice AI assistant to extend and customize.
• A voice pipeline built on LiveKit Inference, which gives you access to models from top labs with no extra configuration:
  • The default LLM is Gemma 4 31B, an open-weight model hosted by LiveKit and tuned for voice AI.
  • The default TTS is Fish Audio S2.1 Pro, an expressive and cost-effective voice.
  • More than 50 other models are available from OpenAI, Cartesia, Deepgram, and other providers.
  • Realtime models such as OpenAI GPT-Live, OpenAI GPT Realtime, xAI Grok Voice, and Google Gemini Live, also with no provider API key.
  • Many other models are available through the plugin ecosystem.
• Expressive mode, on by default, so your agent’s voice carries emotion and pacing that fit the conversation.
• LiveKit Turn Detector, which knows when the user has finished speaking, in 14 languages.
• Adaptive interruption handling, which tells a real interruption from an “uh-huh” or background noise, so your agent doesn’t stop talking when it shouldn’t.
• Background voice cancellation.
• Session transcripts, traces, and recordings from LiveKit Agent Observability.
• Simulations that test full conversations with your agent, run in CI on every merge to main.
• A Dockerfile for deploying to LiveKit Cloud.

The starter works with any custom web or mobile frontend or with telephony.

Using coding agents

This project works with coding agents like Claude Code, Cursor, and Codex.

LiveKit offers both a CLI and an MCP server for browsing and searching its documentation. Search returns short excerpts, so fetch the full page to read the details:

lk docs search "testing my agent"
lk docs get-page /testing/unit-tests

The project also includes an AGENTS.md file, so your coding agent follows LiveKit’s best practices for workflows, handoffs, and testing, and tries its changes with the agent debugger.

For more guidance at each stage of the work, from building and debugging to testing and deploying, install LiveKit’s agent skills. The CLI installs them for the coding agents on your machine and adds the Docs MCP server to their config. lk agent init offers to do this when it creates your project, or you can run it yourself:

lk skills install

Run lk skills update to get the latest skills, and commit skills-lock.json along with them. See the coding agents guide for more details.

Dev setup

Install the LiveKit CLI, version 2.18.8 or later:

• macOS: brew install livekit-cli
• Linux: curl -sSL https://get.livekit.io/cli | bash
• Windows: winget install LiveKit.LiveKitCLI

Check your version with lk --version. To update an existing install, see Update the CLI.

Then create a project from this template. The CLI clones the template and configures your environment:

lk cloud auth
lk agent init my-agent --template agent-starter-node

Run the agent

The lk agent console, lk agent dev, and lk agent debugger commands run your agent on your own machine. To talk to it in your terminal:

lk agent console

To connect it to LiveKit Cloud so a frontend, a phone call, or the Agent Console can reach it:

lk agent dev

To let a coding agent or a script test it one text turn at a time, use the agent debugger. Each turn prints the agent’s reply along with the tool calls and handoffs behind it:

lk agent debugger start
lk agent debugger say "Hi, what can you do?"
lk agent debugger stop

In production, run the agent directly:

node src/main.ts start

Frontends and telephony

Pair the agent with a prebuilt frontend starter, or add telephony:

For more options, see the frontend guide.

Testing and debugging

Simulations run full multi-turn conversations between a simulated user and your agent on LiveKit Cloud, then judge each transcript. The scenarios live in scenarios.yaml. Run them locally with the CLI:

lk agent simulate text --scenarios scenarios.yaml

The Simulations workflow in .github/workflows/simulations.yml runs the same file on every merge to main, and on demand from the Actions tab. It doesn’t run on every pull request push because each run uses real inference. See the simulations guide for how to write scenarios and read results.

To check a change turn by turn without a live session, use the agent debugger shown in Run the agent.

To debug a running agent, open it in the Agent Console. It shows events, tool calls, and model timing as you talk to the agent. To stream logs from a deployed agent, run lk agent logs.

Using this template for your own project

After you create your own project from this template:

• Commit pnpm-lock.yaml. The template doesn’t track it, but your project should, for reproducible builds. If you deploy to LiveKit Cloud, commit livekit.toml too.
• Add repository secrets. Add LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET as repository secrets so the simulations can run in CI.

Deploying to production

To deploy the agent to LiveKit Cloud or another environment with the included Dockerfile, see the deployment guide.

Self-hosted LiveKit

You can self-host LiveKit instead of using LiveKit Cloud. See the self-hosting guide. If you self-host, use model plugins instead of LiveKit Inference, and remove the LiveKit Cloud noise cancellation plugin.

License

This project is licensed under the MIT License. See LICENSE for details.