The provided document describes "Agent Starter for React," a public template designed for building voice interfaces with LiveKit Agents, leveraging the Agents UI components and LiveKit JavaScript SDK. This starter serves as a foundational application for real-time voice interactions, offering features such as camera video streaming, screen sharing, multiple audio visualizer styles (bar, grid, radial, wave, aura), virtual avatar integration, and customizable theming with light/dark mode support. It is built using Next.js.

The core methodology revolves around the integration and customization of pre-built UI components from the LiveKit Agents UI library and Shadcn/ui. The project structure is organized to separate concerns, with application-specific logic residing primarily within the components/app directory.

The technical architecture and component breakdown are as follows:

• Project Structure: The agent-starter-react/ directory includes standard Next.js folders like app/ (for API routes and page rendering), public/ (for static assets), styles/, and configuration files like package.json, next.config.ts. Crucially, the components/ directory is further subdivided into:
  • agents-ui/: Contains the Agents UI components, which are installed and managed like Shadcn components.
  • ai-elements/: AI-specific elements.
  • app/: Houses the application's core business logic, state management, and composition of various UI components.
  • ui/: Primitive Shadcn/ui components.
• Business Logic within components/app/: This folder orchestrates the application's state and behavior. Key files include:
  • session-view.tsx: Responsible for initializing the LiveKit session, rendering the main view controller, and displaying the session UI, including the chat transcript, media tiles, and the control bar.
  • view-controller.tsx: Manages transitions between the "welcome" and "session" views, dynamically adapting based on the current LiveKit session state (connected or disconnected).
  • welcome-view.tsx: Renders the initial user interface displayed when the LiveKit session is not yet established.
  • chat-transcript.tsx: Handles the display and management of chat messages and transcription updates during the session.
  • tile-layout.tsx: Manages the dynamic layout and transitions of media tiles (e.g., video feeds of participants) based on application states.
• LiveKit Session Integration: Most Agents UI components require access to a Session object from the LiveKit SDK to retrieve agent state, audio tracks, and other session-related data. This is achieved by wrapping components within an AgentSessionProvider. This provider obtains the Session object, typically derived from a TokenSource, and makes it available to its child components through React Context, ensuring proper data flow for real-time interactions.
• Component Customization and Maintenance: Agents UI components, following Shadcn's philosophy, are designed to be highly customizable. They extend standard HTML attributes (e.g., $HTMLAttributes<HTMLDivElement>$), allowing developers to pass any valid HTML props directly. Styling is primarily managed through Tailwind CSS classes, which can be overridden by passing custom classes. The source code of Agents UI components is directly available in components/agents-ui, enabling deep customization. Updates to these components are managed via the pnpm shadcn:install command, while new components can be added using pnpm dlx shadcn@latest add @agents-ui/{component-name}. The CLI prompts before overwriting modified files, preserving local customizations.

Configuration and Environment:
The starter is highly configurable via app-config.ts, which defines APP_CONFIG_DEFAULTS. This file allows customization of:

• Branding: companyName, pageTitle, logo, logoDark, accent, accentDark.
• Feature Toggles: supportsChatInput, supportsVideoInput, supportsScreenShare, isPreConnectBufferEnabled.
• UI Text: startButtonText.
• Audio Visualizer Presets: Configurable through audioVisualizerType (e.g., 'bar', 'grid', 'radial', 'wave', 'aura') and type-specific parameters like audioVisualizerBarCount, audioVisualizerGridRowCount, audioVisualizerRadialBarCount, audioVisualizerRadialRadius, audioVisualizerWaveLineWidth, and audioVisualizerAuraColorShift. A shared audioVisualizerColor can be set.
• Agent Dispatch: agentName (for explicit dispatch) and sandboxId (for LiveKit Cloud Sandbox).

Essential LiveKit credentials and agent dispatch settings are configured via environment variables in a .env.local file (copied from .env.example), including LIVEKIT_API_KEY, LIVEKIT_API_SECRET, LIVEKIT_URL, and optionally AGENT_NAME for specific agent routing.

Deployment involves cloning the template, installing dependencies with pnpm install, and running the development server with pnpm dev. It also integrates with LiveKit Cloud Sandbox for quick deployment via lk app create --template agent-starter-react.