React 版 Agent 启动模板

这是 LiveKit Agents 的启动模板，它提供了一个使用 Agents UI 组件和 LiveKit JavaScript SDK 构建的简洁语音交互界面。该模板支持语音、转录以及虚拟数字人功能。

同时也提供以下平台的版本： Android • Flutter • Swift • React Native

功能特性：

• 与 LiveKit Agents 进行实时语音交互
• 支持摄像头视频流
• 支持屏幕共享
• 多种音频可视化风格（bar、grid、radial、wave、aura）
• 集成虚拟数字人
• 支持深色/浅色模式切换，并可检测系统偏好
• 可通过配置自定义品牌、颜色和 UI 文本

该模板基于 Next.js 构建，您可以根据需要自由使用或修改。

项目结构

本模板使用 Agents UI 组件来实现媒体控制、音频可视化、聊天记录和会话数据展示等核心 UI 元素。Shadcn 会将组件安装到 components/ 文件夹中，因此您可以像操作其他本地组件一样对其进行自定义。

agent-starter-react/
├── app/
│   ├── api/
├── components/
│   ├── agents-ui/     - Agents UI 组件
│   ├── ai-elements/   - AI Elements 组件
│   ├── app/           - 应用专属组件
│   ├── ui/            - 基础 shadcn/ui 组件
├── fonts/
├── hooks/
├── lib/
├── public/
└── package.json

业务逻辑位于 components/app 文件夹中。在这里管理应用程序的状态和行为，并将各种 Shadcn UI 组件组合在一起。

文件	描述
session-view.tsx	初始化应用程序和 LiveKit 会话。渲染视图控制器和会话 UI，包括聊天记录、媒体磁贴和控制栏。
view-controller.tsx	根据 LiveKit 会话状态管理欢迎视图和会话视图之间的切换。
welcome-view.tsx	在 LiveKit 会话未连接时渲染欢迎 UI。
chat-transcript.tsx	管理聊天记录的转换。
tile-layout.tsx	在各种应用状态下管理媒体磁贴的布局和过渡。

组件使用

大多数 Agents UI 组件需要访问 LiveKit 会话对象，以便获取代理状态或音频轨道等数值。会话对象可以通过 TokenSource 创建，并通过将组件包装在 AgentSessionProvider 中来提供。

请参考 components/app/app.tsx 查看本应用中实现此功能的示例。

自定义组件

Agents UI 组件与大多数 Shadcn 组件一样，尽可能多地接受原生属性。例如，AgentControlBar 组件扩展了 HTMLAttributes，因此您可以传递 div 支持的任何 props。这使得扩展组件以实现您自己的样式或功能变得非常容易。

您可以编辑 components/agents-ui 目录中任何 Agents UI 组件的源代码。对于样式更改，我们建议传入 Tailwind 类来覆盖默认样式。请查看源代码以了解如何覆盖组件的默认样式。

更新组件

要将 Agents UI 组件更新为最新版本，请运行以下命令：

pnpm shadcn:install

[!NOTE] CLI 在覆盖任何已修改的文件之前会询问您，因此您可以避免丢失所做的任何自定义设置。

安装组件

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

入门指南

[!TIP] 如果您想在不进行修改的情况下体验此应用程序，可以部署一个实例。