This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Using LiveKit
Edit page
Add a realtime voice agent to your app with LiveKit.
LiveKit is an open source platform for realtime voice and video. With LiveKit Agents, you can build an AI agent that joins a conversation and talks with your users.
This guide uses the Expo LiveKit template to create a voice agent app for Android and iOS. The template has one screen with a live audio visualizer and a streaming transcript, a token endpoint in an API route, and a voice agent written in TypeScript.
3 requirements
3 requirements
1.
Sign up for LiveKit Cloud and create a project. A free project works for this guide.
2.
Install the LiveKit CLI. This guide uses it to sign in and to write your credentials.
3.
The app uses WebRTC, which Expo Go does not include, so it runs in a development build. This guide creates one with Expo Build or on your computer.
Create a voice agent app
1
2
Connect your LiveKit Cloud project
Sign in with the LiveKit CLI, then write your credentials to .env.local:
lk cloud auth opens a browser window to link your LiveKit Cloud project to the CLI. lk app env -w writes LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET to .env.local. The token endpoint and the agent read these values.
3
Start the agent
The agent connects to LiveKit Cloud and waits for a conversation. It uses a speech-to-speech model from LiveKit Inference, so you do not need an API key from a model provider. Keep this terminal open.
4
Run the app
The app runs in a development build. To create one in the cloud, use Expo Build with EAS CLI. You do not need Android Studio or Xcode. In a second terminal, run:
When the build finishes, install it on your device. Then start the development server:
To create the development build on your computer instead, you need Android Studio or Xcode. See Set up your environment. These commands create the build and start the development server:
To compare the two methods, see Introduction to development builds.
Tap Start conversation and allow microphone access. The agent greets you, and the transcript appears while you talk.
An Android Emulator or iOS Simulator has no echo cancellation, so the agent can hear its own voice from your computer's speakers. Mute the microphone in the app while the agent speaks, or use headphones.
The source code of the template, with notes on how to change the agent, the visualizer, and the colors.
How the template works
The template has three parts: a token endpoint, a hook that holds the LiveKit session code, and the voice agent.
Token endpoint
The app needs a token to join a LiveKit room. src/app/token+api.ts is an API route that creates a token for a new room and dispatches the agent to that room. The route runs on the server, so the API secret never reaches the app.
API routes need web.output set to server in app.json, which the template already does. In development, the Expo development server runs the route.
Voice session hook
All LiveKit session code is in src/hooks/use-voice-session.ts. The useVoiceSession hook uses useSession from @livekit/components-react with the token endpoint as its token source. It asks for microphone access before it connects, so the agent does not greet the user behind the permission dialog.
The hook returns the state of the conversation and the functions to control it. You can build your own screen on top of it:
The template's own screen also shows an audio visualizer from LiveKit Agents UI. The visualizers are React components for the web, and they run in a DOM component.
Voice agent
agent/agent.ts is the voice agent. It joins the room, starts a session with a realtime model, and greets the user:
To change how the agent behaves, edit its instructions, voice, and model in this file. The agentName must match AGENT_NAME in the token endpoint.
Learn how to add tools, change models, and design the conversation of your voice agent.
Deploy to production
In development, the app gets tokens from the Expo development server and the agent runs on your computer. Before you ship, protect and deploy the token endpoint, then deploy the agent.
1
Protect the token endpoint
The token endpoint in the template issues a token to anyone who calls it. Before you deploy it, add a check to src/app/token+api.ts that the request comes from a signed-in user. See Authentication for the options.
2
Deploy the token endpoint
Export the server and deploy it to Expo Hosting with EAS CLI:
eas deploy uploads the LiveKit credentials in .env.local with the deployment. See environment variables in Expo Hosting for other ways to provide them.
3
Set the origin
A production build has no development server, so tell the app where the token endpoint is. Set the deployed URL as the origin of the expo-router config plugin in app.json, then create a new build:
See Native deployment for more information about API routes in native apps.
4
Learn how LiveKit Cloud builds and runs your agent, and how to check its status and logs.
Troubleshooting
The app does not open in Expo Go
LiveKit uses WebRTC, which needs native code that Expo Go does not include. Run the app in a development build. See Run the app.
The app stays on "Connecting"
The app waits for the agent to join the room. Check that npm run agent is still running and that it uses the same LiveKit Cloud project as the app. Also check that agentName in agent/agent.ts matches AGENT_NAME in src/app/token+api.ts.
The agent does not hear you on an Android Emulator
The Android Emulator does not use your computer's microphone by default. After the emulator starts, turn on the microphone input:
A production build shows "No token server"
The app has no origin for the token endpoint. See Set the origin.
A production build fails with "requireNativeComponent is not a function"
Expo loads the root layout in Node.js when it exports the token endpoint, and the LiveKit native modules cannot load there. The template has src/app/_layout.web.tsx for this case. Keep this file, and do not import @livekit/react-native in a layout file without a web version.