agent-starter-react 是一个基于 Next.js 和 React 19 构建的语音AI前端完整模板，专为 LiveKit Agents 实时语音框架打造。它把语音对话、音视频流、屏幕共享、虚拟形象等能力封装成开箱即用的 Web 界面，让你不用从零搭建 UI，几分钟内就能跑通一个可对话的语音 AI 应用。

为什么需要这个语音AI前端模板？

很多开发者会问：后端 Agent 写好了，前端界面怎么做？如果自行开发，WebSocket 连接管理、音频可视化、麦克风/摄像头控制、深浅色主题……每一项都要花时间，从零写起往往需要数周。

agent-starter-react 直接给出了答案：

• 完整语音 UI：欢迎页、通话页、消息转写、控制栏一应俱全
• 官方组件加持：基于 LiveKit 官方 Agents UI 组件与 JavaScript SDK 封装，代码规范可长期维护
• 高度可定制：品牌、配色、功能开关全部集中在一个配置文件里
• 跨端生态：同系列还有 Android、Flutter、Swift、React Native 版本可对照参考

快速开始：三步跑通语音AI应用

一键获取项目

从仓库克隆代码：

git clone https://gitcode.com/gh_mirrors/ag/agent-starter-react cd agent-starter-react

如果你已经安装了 LiveKit CLI，也可以用模板命令自动创建：

lk app create --template agent-starter-react

最快配置方法：填入 LiveKit 凭证

在项目根目录创建.env.local文件（可参考.env.example），填入你的 LiveKit 项目凭证：

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

这三个参数用于服务端签发接入用的 JWT 凭证，签发逻辑见 app/api/token/route.ts。

启动开发服务器

pnpm install pnpm dev

打开http://localhost:3000即可看到欢迎页，点击 "Start call" 按钮开始与语音 Agent 通话。

💡 小提醒：浏览器默认阻止自动播放音频。若连接后没有声音，页面会出现Start Audio按钮，点击一次即可恢复播放。该按钮由 components/agents-ui/start-audio-button.tsx 实现。

7大核心功能详解

功能一：实时语音对话

核心交互流程由 components/app/view-controller.tsx 驱动：未连接时显示欢迎页，连接后自动平滑切换到通话视图。欢迎页中的声波图标与 "Start call" 按钮定义在 components/app/welcome-view.tsx。

通话中支持双向实时语音，AI 回复会以聊天气泡形式实时呈现；控制栏内还带文字输入框，可以"打字 + 说话"混合交流。

功能二：5款音频可视化特效

模板内置五种音频可视化样式，改一行配置即可切换：

五种样式分别实现在 agent-audio-visualizer-bar.tsx、agent-audio-visualizer-grid.tsx、agent-audio-visualizer-radial.tsx、agent-audio-visualizer-wave.tsx 和 agent-audio-visualizer-aura.tsx 中，还可通过audioVisualizerColor统一设定主题色。

功能三：摄像头视频流

将supportsVideoInput设为true后，控制栏会显示摄像头开关。打开后本地摄像头画面以"小窗悬浮"形式展示，Agent 侧也能订阅视频轨道——配合视觉模型即可实现"看得见"的 AI 对话。

功能四：屏幕共享

supportsScreenShare开启后，控制栏提供屏幕共享按钮（见 agent-control-bar.tsx）。这一能力非常适合"AI 看图讲解"类场景：把演示文稿或代码页面共享给 Agent 实时解读。

功能五：虚拟形象（Virtual Avatar）集成

模板原生支持 LiveKit 虚拟形象方案：当会话中出现虚拟形象的视频轨道时，主画面区域会自动渲染该视频流（布局逻辑见 tile-view.tsx），让语音 AI 拥有"数字人"面孔。

功能六：深浅色主题自动切换

通过next-themes实现 Light / Dark 双主题，并自动跟随系统偏好。主题提供器位于 components/app/theme-provider.tsx，切换按钮在 components/app/theme-toggle.tsx。音频可视化特效也支持为深色模式单独指定颜色。

功能七：一键品牌定制

所有"外观"与"功能开关"都集中在 app-config.ts，例如：

companyName: 'LiveKit', pageTitle: 'LiveKit Voice Agent', logo: '/lk-logo.svg', accent: '#002cf2', startButtonText: 'Start call', supportsChatInput: true, supportsVideoInput: true, supportsScreenShare: true,

改公司名、换 Logo、调主题色、关屏幕共享……全部只动这一个文件，无需修改组件代码。

项目结构速览

agent-starter-react/ ├── app/ # Next.js 应用入口与 Token API ├── components/ │ ├── agents-ui/ # Agents UI 组件：可视化、控制栏、转写 │ ├── ai-elements/ # AI 消息元素：对话气泡、闪烁提示 │ ├── app/ # 业务逻辑：视图控制、欢迎页、主题 │ └── ui/ # shadcn/ui 基础组件 ├── hooks/ # 音频可视化与控制栏 Hook ├── lib/ # 工具函数 └── app-config.ts # 全局配置

业务状态集中在components/app/目录（入口组合见 components/app/app.tsx）；而 shadcn 风格的 UI 组件源码就在本地components/下，你可以像改普通文件一样改样式和逻辑。升级组件只需执行：

pnpm shadcn:install

CLI 在覆盖文件前会先询问，避免丢失你的自定义改动。更多说明见 README.md。

进阶部署：LiveKit Cloud Sandbox

如果只想快速体验而不想本地折腾，可以直接把模板部署到 LiveKit Cloud Sandbox，获得一个可分享的 URL。与同一 LiveKit 项目下运行的 Agent 会自动加入房间，方便你快速迭代原型并把链接直接发给同事演示（沙箱参数sandboxId在 app-config.ts 中配置）。

常见问题 FAQ

Q：点 "Start call" 后为什么没有声音？A：浏览器自动播放策略所致，点击页面上出现的Start Audio按钮即可。

Q：如何指定连接的 Agent？A：在.env.local中设置AGENT_NAME可显式分发到指定 Agent；留空则走自动分发。

Q：生产环境要注意什么？A：app/api/token/route.ts 中的 Token 接口仅限开发环境，生产部署前务必补充鉴权层。

总结

agent-starter-react 把"语音 AI 前端"从数周工作量压缩到几分钟：一个配置文件搞定品牌定制，五种可视化特效随选，摄像头、屏幕共享、虚拟形象开箱即用。配合 LiveKit Agents，它是目前上手实时语音 AI 应用最快的前端模板之一。