Agent Starter for React

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

Features:

• Real-time voice interaction with LiveKit Agents
• Camera video streaming support
• Screen sharing capabilities
• Multiple audio visualizer styles (bar, grid, radial, wave, aura)
• Virtual avatar integration
• Light/dark theme switching with system preference detection
• Customizable branding, colors, and UI text

This template is built with Next.js and is free for you to use or modify as you see fit.

Getting started

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 dev

Then 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).

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.

Token generation in production

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.

Project structure

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.

Component usage

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.

Customizing components

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.

Updating components

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.

Installing components

pnpm dlx shadcn@latest add @agents-ui/{component-name-a} @agents-ui/{component-name-b}

Configuration

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.

Audio visualizer presets

Set audioVisualizerType in components/app/view-controller.tsx to switch visualizer styles:

• bar (default): vertical bars with optional audioVisualizerBarCount
• grid: dot grid with audioVisualizerGridRowCount and audioVisualizerGridColumnCount
• radial: circular bars with audioVisualizerRadialBarCount and audioVisualizerRadialRadius
• wave: oscilloscope-style wave with audioVisualizerWaveLineWidth
• aura: shader-based aura with audioVisualizerAuraColorShift

Use audioVisualizerColor to set a shared accent color across all visualizer modes.

Contributing

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!