Agent Starter React

Agent Starter for React is a Next.js frontend designed for building AI voice assistant interfaces. It utilizes the LiveKit JavaScript SDK and LiveKit React Components to provide out-of-the-box support for:

• Voice: Real-time AI voice interactions.
• Transcription: Textual representation of audio streams.
• Virtual Avatars: Integration with visual avatar representations.

The application includes its own token server to handle authentication and session management for LiveKit agents.

The project is organized into several key directories:

• components/agents-ui/: Core Agents UI components.
• components/app/: Business logic lives here. This folder manages application state, behavior, and the composition of Shadcn UI components.
• components/ui/: Primitive Shadcn/ui components.
• app/api/: Next.js API routes.

Key files in components/app include:

• session-view.tsx: Initializes the LiveKit session and renders the main UI (chat, media tiles, control bar).
• view-controller.tsx: Manages transitions between the welcome view and the active session view.
• welcome-view.tsx: The UI shown before a session is connected.
• chat-transcript.tsx: Manages chat transcript transitions.
• tile-layout.tsx: Manages media tile layouts and transitions.

Most Agents UI components require access to a LiveKit session object to retrieve agent state or audio tracks.

To use these components, you must:

1. Create a Session object (e.g., from a TokenSource).
2. Wrap your component tree in an AgentSessionProvider to provide the session context to the components.

To start a new project using this template, use the LiveKit CLI to clone it, then install dependencies and run the development server.

1. Clone the template:

   lk app create --template agent-starter-react

2. Install dependencies:

   pnpm install

3. Run the app:

   pnpm dev

Access the application at http://localhost:3000. Note that you will need a running LiveKit Agent (e.g., Python or Node.js starter) to interact with the interface.

LiveKit Sandbox allows you to deploy this application to a hosted instance that provides a unique, shareable URL.

To iterate on agent prototypes:

1. Deploy the application in the Sandbox.
2. Set up your agent on your local machine (e.g., using the LiveKit Voice AI Quickstart).
3. Agents running with the same LiveKit project credentials will automatically join the sandbox session, allowing you to test and share your results instantly.

You can quickly scaffold a new project using this template by using the LiveKit CLI. This is the recommended way to start a local development environment for this starter kit.

lk app create --template agent-starter-react

To connect the frontend to your LiveKit project, configure the following variables in a .env.local file:

• LIVEKIT_API_KEY: Your LiveKit API key.
• LIVEKIT_API_SECRET: Your LiveKit API secret.
• LIVEKIT_URL: Your LiveKit server URL.
• AGENT_NAME: (Optional) Used for explicit agent dispatch. Leave blank to enable automatic dispatch.

LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
LIVEKIT_URL=https://your-livekit-server-url

# Agent dispatch
AGENT_NAME=

This project uses Shadcn-style components located in components/agents-ui.

Customizing Styles

Agents UI components accept standard HTML attributes. For example, AgentControlBar extends HTMLAttributes<HTMLDivElement>. To override default styles, it is recommended to pass Tailwind CSS classes directly to the component props or edit the source code in components/agents-ui.

Updating Components

To update the Agents UI components to the latest version, run:

pnpm shadcn:install

The CLI will prompt you before overwriting any files you have customized.

Installing New Components

To add a specific Agents UI component to your project, use:

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

pnpm shadcn:install
# or to add a specific component
pnpm dlx shadcn@latest add @agents-ui/agent-control-bar

The App component's behavior regarding agent dispatching is determined by the agentName property within the appConfig object passed to the App component:

• Automatic Dispatch: Leave agentName blank or undefined. The application will attempt to connect to an available agent automatically.
• Explicit Dispatch: Provide a specific string to agentName. This tells the LiveKit server to dispatch a specific agent type to the session.

You can change the visual style of the audio visualizer by setting the audioVisualizerType in app-config.ts. Each type has specific optional configuration keys:

• bar (default): Vertical bars. Use audioVisualizerBarCount to set the number of bars.
• grid: A dot grid. Use audioVisualizerGridRowCount and audioVisualizerGridColumnCount.
• radial: Circular bars. Use audioVisualizerRadialBarCount and audioVisualizerRadialRadius.
• wave: Oscilloscope-style wave. Use audioVisualizerWaveLineWidth.
• aura: Shader-based aura. Use audioVisualizerAuraColorShift.

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

The getSandboxTokenSource function returns a TokenSource.custom instance used to obtain connection details for a sandboxed LiveKit session.

It performs a POST request to the endpoint defined by NEXT_PUBLIC_CONN_DETAILS_ENDPOINT.

Request Details:

• Headers: Includes X-Sandbox-Id (from appConfig.sandboxId).
• Body: A JSON object containing room_config. If appConfig.agentName is provided, the room_config will include an agents array specifying that agent: { agents: [{ agent_name: appConfig.agentName }] }.

This is used to bridge the React frontend with the LiveKit backend for sandboxed agent interactions.

import { getSandboxTokenSource } from '@/lib/utils';

const tokenSource = getSandboxTokenSource(appConfig);
// This tokenSource can then be used with LiveKit client components