gem-hunter
Language: TypeScript
A complete voice AI frontend app for LiveKit Agents with Next.js
This is a starter template for LiveKit Agents that provides a simple voice interface using Agents UI components and LiveKit JavaScript SDK. It supports voice, transcriptions, and virtual avatars.
Also available for: Android • Flutter • Swift • React Native
bar, grid, radial, wave, aura)This template is built with Next.js and is free for you to use or modify as you see fit.
Clone this template, install dependencies, and run the app:
git clone https://github.com/livekit-examples/agent-starter-react.git
cd agent-starter-react
pnpm install
pnpm devThen open http://localhost:3000 in your browser.
The app is configured to connect to the LiveKit homepage agent by default, which you can also try at livekit.com. That agent takes voice and text input only, so video and screen sharing are hidden until you point the app at your own agent (see Connect to your agent).
To switch from the default agent to your own, you first need a LiveKit agent to speak with. For a no-code setup, use the Agent Builder. For more customization, try our starter agent for Python, Node.js, or create your own from scratch.
Second, you need a token server. For development, the easiest option is the development token server: switch on the Development token server toggle on your project's Settings page in LiveKit Cloud and copy the Token server ID below it. Then copy .env.example to .env.local and fill it in:
LIVEKIT_TOKEN_SERVER_ID=<your-token-server-id>
Alternatively, use the token endpoint included in this app at app/api/token/route.ts. It needs your project's LiveKit credentials in .env.local, which the LiveKit CLI fills in for you when it clones the template:
lk app create --template agent-starter-react
Or copy them from your project's Settings page yourself:
LIVEKIT_URL=wss://<project-subdomain>.livekit.cloud LIVEKIT_API_KEY=<your_api_key> LIVEKIT_API_SECRET=<your_api_secret>
Leave AGENT_NAME blank for automatic dispatch, or set it to your agent's name for explicit dispatch.
Note
Both options are for development only — any client can request a token. See Token generation in production before you ship.
In production, you will be responsible for developing a solution to generate tokens for your users that integrates with your authentication system. Add an authentication layer to app/api/token/route.ts, or point tokenEndpoint in app/page.tsx at your own token server and drop the development token server.
This starter uses the Agents UI components for core UI elements like media controls, audio visualizers, chat transcripts, and providing session data. Shadcn installs components into components/ folder so you can customize them like any other local component.
agent-starter-react/
├── app/
│ ├── api/
├── components/
│ ├── agents-ui/ - Agents UI components
│ ├── app/ - App-specific components
│ ├── ui/ - Primitive shadcn/ui components
├── fonts/
├── hooks/
├── lib/
├── public/
└── package.json
Business logic lives within the components/app folder. It's here where the application's state and behavior is managed and the various Shadcn UI components are composed together.
| File | Description |
|---|---|
session-view.tsx |
Initializes the application, and LiveKit session. Renders the view controller and session UI including chat transcript, media tiles, and control bar. |
view-controller.tsx |
Manages the transitions between the welcome and session views based on the LiveKit session state. |
welcome-view.tsx |
Renders the welcome UI when the LiveKit session is not connected. |
chat-transcript.tsx |
Manages the chat transcript transitions. |
tile-layout.tsx |
Manages the layout and transition of media tiles in various application states. |
Most Agents UI components require access to a LiveKit session object for access to values like agent state or audio tracks. A Session object can be created from a TokenSource, and provided by wrapping the component in an AgentSessionProvider.
See components/app/app.tsx for an example of how this is done in this app.
Agents UI components, like most Shadcn components, take as many primitive attributes as possible. For example, the AgentControlBar component extends HTMLAttributes<HTMLDivElement>, so you can pass any props that a div supports. This makes it easy to extend the component with your own styles or functionality.
You can edit any Agents UI component's source code in the components/agents-ui directory. For style changes, we recommend passing in tailwind classes to override the default styles. Take a look at the source code to get a sense of how to override a component's default styles.
To update the Agents UI components to the latest publication, run the following command:
pnpm shadcn:install
Note
The CLI will ask before overwriting any modified files so you can avoid losing any customizations you might have made.
pnpm dlx shadcn@latest add @agents-ui/{component-name-a} @agents-ui/{component-name-b}This starter is designed to be flexible so you can adapt it to your specific agent use case. Branding, feature toggles, and UI text are set directly in the components that use them — see app/layout.tsx for branding (logo, colors, page title/description) and components/app/view-controller.tsx for feature toggles and the audio visualizer. Video and screen share input follow the connected agent; override isVideoInputSupported in app/page.tsx to force them on or off.
Set audioVisualizerType in components/app/view-controller.tsx to switch visualizer styles:
bar (default): vertical bars with optional audioVisualizerBarCountgrid: dot grid with audioVisualizerGridRowCount and audioVisualizerGridColumnCountradial: circular bars with audioVisualizerRadialBarCount and audioVisualizerRadialRadiuswave: oscilloscope-style wave with audioVisualizerWaveLineWidthaura: shader-based aura with audioVisualizerAuraColorShiftUse audioVisualizerColor to set a shared accent color across all visualizer modes.
This template is open source and we welcome contributions! Please open a PR or issue through GitHub, and don't forget to join us in the LiveKit Community Slack!