A starter project for building voice AI apps with LiveKit Agents for Node.js and LiveKit Cloud.
-
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:
lk cloud auth - macOS:
-
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 initinstall dependencies, runpnpm installfirst.
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
Dockerfilefor deploying to LiveKit Cloud.
The starter works with any custom web or mobile frontend or with telephony.
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 consoleTo connect it to LiveKit Cloud so a frontend, a phone call, or the Agent Console can reach it:
lk agent devTo 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 stopIn production, run the agent directly:
node src/main.ts startPair the agent with a prebuilt frontend starter, or add telephony:
| Platform | Link | Description |
|---|---|---|
| Web | livekit-examples/agent-starter-react |
Web voice AI assistant with React & Next.js |
| iOS/macOS | livekit-examples/agent-starter-swift |
Native iOS, macOS, and visionOS voice AI assistant |
| Flutter | livekit-examples/agent-starter-flutter |
Cross-platform voice AI assistant app |
| React Native | livekit-examples/voice-assistant-react-native |
Native mobile app with React Native & Expo |
| Android | livekit-examples/agent-starter-android |
Native Android app with Kotlin & Jetpack Compose |
| Web Embed | livekit-examples/agent-starter-embed |
Voice AI widget for any website |
| Telephony | Documentation | Add inbound or outbound calling to your agent |
For more options, see the frontend guide.
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.yamlThe 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.
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:
lk skills installTo 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.
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, commitlivekit.tomltoo. - Commit the agent skills and
skills-lock.json, if you installed them in the project. - Add repository secrets. Add
LIVEKIT_URL,LIVEKIT_API_KEY, andLIVEKIT_API_SECRETas repository secrets so the simulations can run in CI.
To deploy the agent to LiveKit Cloud, see the deployment guide.
This project is licensed under the MIT License. See LICENSE for details.