LiveKit Agents starter for Node.js
A starter project for building voice AI apps with LiveKit Agents for Node.js and LiveKit Cloud.
Getting started
-
Install Node.js 24 or later and pnpm.
-
Install the LiveKit CLI and sign in to LiveKit Cloud:
- macOS:
brew install livekit-cli
- Linux:
curl -sSL https://get.livekit.io/cli | bash
- Windows:
winget install LiveKit.LiveKitCLI
Sign up for a free LiveKit Cloud account if you don't have one, then link it to the CLI:
-
Create your project from this starter:
lk agent init my-agent --template agent-starter-node
-
Talk to your agent. Run it in your terminal and speak into your microphone:
cd my-agent
lk agent console
If you didn't let lk agent init install dependencies, run pnpm install first.
What's included
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.
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:
To connect it to LiveKit Cloud so a frontend, a phone call, or the Agent Console can reach it:
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:
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 coding agents
This project works with coding agents like Claude Code, Cursor, and Codex.
Agent skills. Install LiveKit's agent skills, which teach your coding agent to build, debug, test, and deploy LiveKit agents:
To get the latest skills, run lk skills update.
AGENTS.md. Teaches your coding agent LiveKit's best practices for workflows, handoffs, and testing, and has it check its changes with the agent debugger.
For more, see the coding agents guide.
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.
- Commit the agent skills and
skills-lock.json, if you installed them in the project.
- 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, see the deployment guide.
License
This project is licensed under the MIT License. See LICENSE for details.