agent-starter-react 문서는 LiveKit Agents를 위한 React 기반의 스타터 템플릿에 대해 상세히 설명합니다. 이 템플릿은 LiveKit JavaScript SDK와 Agents UI components를 활용하여 간단한 음성 인터페이스를 제공하며, 음성, 트랜스크립션(transcriptions), 가상 아바타(virtual avatars) 기능을 지원합니다. Next.js로 구축되었으며, Android, Flutter, Swift, React Native 버전도 제공됩니다.

주요 기능은 다음과 같습니다: LiveKit Agents와의 실시간 음성 상호작용(Real-time voice interaction), 카메라 비디오 스트리밍(Camera video streaming) 및 화면 공유(Screen sharing) 기능, bar, grid, radial, wave, aura 등 다양한 오디오 시각화(audio visualizer) 스타일, 가상 아바타 통합, 시스템 환경설정을 감지하는 라이트/다크 테마 전환, 그리고 app-config.ts 파일을 통한 브랜드(branding), 색상, UI 텍스트 사용자 정의입니다.

프로젝트 구조는 agent-starter-react/ 아래에 핵심 UI 요소들을 포함합니다. app/ 폴더는 API 라우트와 페이지를, components/는 Agents UI components, AI Elements components, 애플리케이션 특정(app-specific) components, 그리고 Shadcn/ui의 primitive components를 포함합니다. fonts/, hooks/, lib/, public/ 등 웹 애플리케이션의 일반적인 디렉토리 구조를 따릅니다. 핵심 비즈니스 로직은 components/app 폴더 내에 위치하며, 애플리케이션의 상태와 동작을 관리하고 다양한 Shadcn UI components를 조합합니다. 예를 들어, session-view.tsx는 애플리케이션과 LiveKit 세션을 초기화하고 세션 UI를 렌더링하며, view-controller.tsx는 LiveKit 세션 상태에 따라 welcome 및 session 뷰 간의 전환을 관리합니다. welcome-view.tsx는 세션 연결 전 초기 UI를, chat-transcript.tsx는 채팅 기록 전환을, tile-layout.tsx는 미디어 타일(media tiles)의 레이아웃을 관리합니다.

핵심 방법론은 Agents UI components를 사용하는 것입니다. 대부분의 Agents UI components는 Agent 상태나 오디오 트랙(audio tracks)과 같은 값에 접근하기 위해 LiveKit Session 객체가 필요합니다. Session 객체는 TokenSource로부터 생성될 수 있으며, AgentSessionProvider로 컴포넌트를 감싸서 제공됩니다. components/app/app.tsx에서 이 방식의 예시를 찾아볼 수 있습니다. Agents UI components는 Shadcn components와 유사하게 가능한 한 많은 primitive 속성을 받습니다. 예를 들어, AgentControlBar 컴포넌트는 $HTMLAttributes<HTMLDivElement>$를 확장하므로, div가 지원하는 모든 props를 전달할 수 있습니다. 이를 통해 컴포넌트에 사용자 정의 스타일이나 기능을 쉽게 확장할 수 있습니다. 스타일 변경을 위해서는 Tailwind CSS 클래스를 전달하여 기본 스타일을 재정의하는 것을 권장하며, components/agents-ui 디렉토리에서 직접 소스 코드를 수정할 수도 있습니다. Agents UI components를 최신 버전으로 업데이트하려면 pnpm shadcn:install 명령을 실행합니다.

애플리케이션의 설정은 app-config.ts 파일을 통해 이루어집니다. APP_CONFIG_DEFAULTS 객체를 통해 companyName, pageTitle, pageDescription, supportsChatInput, supportsVideoInput, supportsScreenShare, logo, accent 색상, startButtonText 등을 포함한 다양한 애플리케이션 전반의 설정과 UI 텍스트를 사용자 정의할 수 있습니다. 또한, audioVisualizerType (bar, grid, radial, wave, aura)과 같은 오디오 시각화 설정 및 관련 파라미터(audioVisualizerBarCount, audioVisualizerGridRowCount, audioVisualizerRadialBarCount 등)도 이 파일에서 구성합니다. agentName 및 sandboxId와 같은 에이전트 디스패치(agent dispatch) 설정도 포함됩니다. LiveKit Credentials는 .env.local 파일에 LIVEKIT_API_KEY, LIVEKIT_API_SECRET, LIVEKIT_URL 및 선택적 AGENT_NAME을 설정하여 구성합니다.

시작하려면 lk app create --template agent-starter-react 명령으로 템플릿을 복제한 다음, pnpm install로 의존성을 설치하고 pnpm dev로 애플리케이션을 실행합니다. 이 템플릿은 오픈 소스이며, 기여(contributions)를 환영합니다. GitHub를 통해 PR(Pull Request)이나 이슈(issue)를 제출할 수 있으며, LiveKit Community Slack에 참여하여 소통할 수 있습니다.