agents-ui

LiveKit Agents UI

使用基于 shadcn 的组件，为 LiveKit 语音 AI Agent 构建 React 前端。

LiveKit MCP 服务工具

此技能与 LiveKit MCP 服务配合使用，可直接访问最新的 LiveKit 文档、代码示例和更新日志。当你需要了解自创建此技能以来可能发生变化的信息时，请使用这些工具。

可用的 MCP 工具：

• docs_search - 搜索 LiveKit 文档站点
• get_pages - 按路径获取特定文档页面
• get_changelog - 获取 LiveKit 软件包的近期版本和更新
• code_search - 在 LiveKit 代码仓库中搜索代码示例
• get_python_agent_example - 浏览 100 多个 Python Agent 示例

何时使用 MCP 工具：

• 你需要最新的 API 文档或功能更新
• 你在寻找近期示例或代码模式
• 你想确认某项功能是否已在近期版本中添加
• 本地参考资料未涵盖某个特定主题

何时使用本地参考资料：

• 你需要快速查阅此技能涵盖的核心概念
• 你正在离线工作，或希望更快地访问常见模式
• 参考资料中的信息已满足你的需求

结合使用 MCP 工具和本地参考资料，效果最佳。

参考资料

根据需要查阅以下资源：

• ./references/livekit-overview.md -- LiveKit 生态概览，以及这些技能如何协同工作
• ./references/components.md -- 所有组件的 API、属性和用法示例

前置条件

• Node.js >= 18
• React 19
• Tailwind CSS 4
• 已在项目中初始化 shadcn/ui

安装

1. 将 LiveKit 注册表添加到 shadcn 配置中

在你的 components.json 中：

{
  "registries": {
    "@agents-ui": "https://livekit.io/ui/r/{name}.json"
  }
}

2. 安装组件

# Install individual components
npx shadcn@latest add @agents-ui/agent-session-provider
npx shadcn@latest add @agents-ui/agent-control-bar
npx shadcn@latest add @agents-ui/agent-audio-visualizer-bar

# Or install multiple at once
npx shadcn@latest add @agents-ui/agent-session-provider @agents-ui/agent-control-bar

组件会复制到你的 components/agents-ui/ 目录中，方便你全面自定义。

快速开始

安装

Agents UI 组件需要同时安装 livekit-client 和 @livekit/components-react：

npm install livekit-client @livekit/components-react

设置 TokenSource

使用 Agents UI 组件前，你需要从 livekit-client 获取 TokenSource，用于处理身份验证。

开发环境（使用 LiveKit Cloud Sandbox）：

import { TokenSource } from 'livekit-client';

const tokenSource = TokenSource.sandboxTokenServer({
  sandboxId: 'your-sandbox-id',
});

生产环境（使用你自己的令牌端点）：

import { TokenSource } from 'livekit-client';

const tokenSource = TokenSource.endpoint('/api/token');

基本语音 Agent 界面

使用 @livekit/components-react 中的 useSession 创建会话，然后将其传递给 AgentSessionProvider：

'use client';

import { useRef, useEffect } from 'react';
import { useSession } from '@livekit/components-react';
import { TokenSource, TokenSourceConfigurable } from 'livekit-client';
import { AgentSessionProvider } from '@/components/agents-ui/agent-session-provider';
import { AgentControlBar } from '@/components/agents-ui/agent-control-bar';
import { AgentAudioVisualizerBar } from '@/components/agents-ui/agent-audio-visualizer-bar';

export function VoiceAgent() {
  // Use useRef to prevent recreating TokenSource on each render
  const tokenSource: TokenSourceConfigurable = useRef(
    TokenSource.sandboxTokenServer({ sandboxId: 'your-sandbox-id' })
  ).current;

  // Create session using useSession hook (required for AgentSessionProvider)
  const session = useSession(tokenSource, {
    agentName: 'your-agent-name',
  });

  // Auto-start session with cleanup
  useEffect(() => {
    session.start();
    return () => session.end();
  }, []);

  return (
    <AgentSessionProvider session={session}>
      <div className="flex flex-col items-center gap-8 p-8">
        <AgentAudioVisualizerBar />
        <AgentControlBar />
      </div>
    </AgentSessionProvider>
  );
}

使用令牌端点的生产环境示例

'use client';

import { useRef, useEffect } from 'react';
import { useSession } from '@livekit/components-react';
import { TokenSource, TokenSourceConfigurable } from 'livekit-client';
import { AgentSessionProvider } from '@/components/agents-ui/agent-session-provider';
import { AgentControlBar } from '@/components/agents-ui/agent-control-bar';
import { AgentAudioVisualizerBar } from '@/components/agents-ui/agent-audio-visualizer-bar';

export function VoiceAgent() {
  const tokenSource: TokenSourceConfigurable = useRef(
    TokenSource.endpoint('/api/token')
  ).current;

  const session = useSession(tokenSource, {
    roomName: 'my-room',
    participantIdentity: 'user-123',
    participantName: 'John',
    agentName: 'my-agent',
  });

  useEffect(() => {
    session.start();
    return () => session.end();
  }, []);

  return (
    <AgentSessionProvider session={session}>
      <div className="flex flex-col items-center gap-8 p-8">
        <AgentAudioVisualizerBar />
        <AgentControlBar />
      </div>
    </AgentSessionProvider>
  );
}

核心组件

AgentSessionProvider

必需的包装组件，为所有子组件提供会话状态。它包装了 @livekit/components-react 中的 SessionProvider，并包含用于播放音频的 RoomAudioRenderer。

你必须使用 @livekit/components-react 中的 useSession 创建会话，并将其传递给 AgentSessionProvider：

import { useRef, useEffect } from 'react';
import { useSession } from '@livekit/components-react';
import { TokenSource, TokenSourceConfigurable } from 'livekit-client';
import { AgentSessionProvider } from '@/components/agents-ui/agent-session-provider';

function MyApp() {
  // Create tokenSource with useRef to prevent recreation
  const tokenSource: TokenSourceConfigurable = useRef(
    TokenSource.endpoint('/api/token')
  ).current;

  // Create session using useSession hook (required)
  const session = useSession(tokenSource, { agentName: 'your-agent' });

  // Start session when component mounts
  useEffect(() => {
    session.start();
    return () => session.end();
  }, []);

  return (
    <AgentSessionProvider session={session}>
      {/* All Agents UI components must be inside this provider */}
    </AgentSessionProvider>
  );
}

AgentControlBar

集成媒体控件和可视化器：

<AgentControlBar />

音频可视化器

五种可视化样式：

// Bar visualizer (horizontal bars)
<AgentAudioVisualizerBar />

// Grid visualizer (dot matrix)
<AgentAudioVisualizerGrid />

// Radial visualizer (circular)
<AgentAudioVisualizerRadial />

// Wave visualizer (waveform)
<AgentAudioVisualizerWave />

// Aura visualizer (ambient glow effect)
<AgentAudioVisualizerAura />

媒体控件

单独的音轨控件：

// Toggle microphone
<AgentTrackToggle source="microphone" />

// Toggle camera
<AgentTrackToggle source="camera" />

// Toggle screen share
<AgentTrackToggle source="screen_share" />

// Full track control with label
<AgentTrackControl source="microphone" />

聊天组件

显示对话记录：

// Full chat transcript
<AgentChatTranscript />

// Typing/thinking indicator
<AgentChatIndicator />

会话控件

// Disconnect button
<AgentDisconnectButton />

// Start audio (for browsers requiring user interaction)
<StartAudioButton />

Agent 状态

AgentSessionProvider 会跟踪以下状态：

• initializing - Agent 正在启动
• listening - Agent 正在聆听用户输入
• thinking - Agent 正在处理或生成回复
• speaking - Agent 正在讲话

使用本地 useAgentState Hook（随 Agents UI 组件一同安装）中的这些状态来自定义界面：

// This hook is local to your project (copied via shadcn CLI)
import { useAgentState } from '@/components/agents-ui/hooks/use-agent-state';

function StatusIndicator() {
  const state = useAgentState();
  
  return (
    <div className="flex items-center gap-2">
      <div className={cn(
        "w-2 h-2 rounded-full",
        state === "speaking" && "bg-green-500",
        state === "listening" && "bg-blue-500",
        state === "thinking" && "bg-yellow-500 animate-pulse",
      )} />
      <span className="capitalize">{state}</span>
    </div>
  );
}

样式

组件使用 Tailwind CSS，并支持通过 className 覆盖样式：

<AgentAudioVisualizerBar 
  className="h-32 w-64 bg-slate-900 rounded-lg"
/>

<AgentControlBar 
  className="gap-4 p-4 bg-white/10 backdrop-blur rounded-full"
/>

自定义

由于组件会复制到你的项目中，因此你可以直接修改它们：

// components/agents-ui/agent-control-bar.tsx
export function AgentControlBar({ className }: { className?: string }) {
  return (
    <div className={cn("flex items-center gap-2", className)}>
      {/* Customize the layout, add/remove controls */}
      <AgentTrackToggle source="microphone" />
      <AgentAudioVisualizerBar className="flex-1" />
      <AgentDisconnectButton />
    </div>
  );
}

必需的包

安装 livekit-client 和 @livekit/components-react：

npm install livekit-client @livekit/components-react

这些包提供：

• livekit-client 中的 TokenSource —— 用于创建令牌来源（沙盒、端点、自定义）的工厂
• @livekit/components-react 中的 useSession —— 创建 AgentSessionProvider 会话所必需的钩子

使用 Agents UI 组件时，不需要 @livekit/components-react 中的 UI 组件（例如 LiveKitRoom、BarVisualizer 或 VoiceAssistantControlBar）。请改用 Agents UI 组件来构建 UI。

使用 @livekit/components-react 中的钩子

Agents UI 需要 @livekit/components-react 提供的 useSession 钩子。你也可以使用此包中的其他钩子来实现自定义行为。这些钩子可在 AgentSessionProvider 中使用：

必需的钩子：

• useSession —— 创建 AgentSessionProvider 所需的会话对象

用于自定义行为的其他钩子：

• useAgent —— 获取包含生命周期辅助工具的完整 Agent 状态（需要使用 useSession 获取会话）
• useVoiceAssistant —— 获取 Agent 状态、轨道和转录文本
• useTrackToggle —— 构建自定义轨道切换按钮
• useChat —— 发送和接收聊天消息
• useParticipants —— 访问房间中的所有参与者
• useConnectionState —— 监控连接状态

import { useVoiceAssistant } from '@livekit/components-react';

// This works inside AgentSessionProvider
function CustomAgentDisplay() {
  const { state, audioTrack, agentTranscriptions } = useVoiceAssistant();
  
  return (
    <div>
      <p>Agent is {state}</p>
      {agentTranscriptions.map((t) => (
        <p key={t.id}>{t.text}</p>
      ))}
    </div>
  );
}

完整的钩子文档请参阅 livekit-react-hooks 技能。

最佳实践

1. 始终使用 AgentSessionProvider 包裹 —— 所有 Agents UI 组件都需要此上下文。
2. 使用 useSession 创建会话 —— 使用 @livekit/components-react 中的 useSession 创建会话，并将其传递给 AgentSessionProvider。
3. 使用 useRef 保存 TokenSource —— 始终将 TokenSource 的创建封装在 useRef 中，以避免每次渲染时重新创建。
4. 正确启动和结束会话 —— 在 useEffect 中调用 session.start()，并在清理函数中调用 session.end()。
5. 处理音频权限 —— 对于需要用户交互的浏览器，请使用 StartAudioButton。
6. 通过 Tailwind 自定义样式 —— 使用 className 属性调整样式。
7. 直接修改源代码 —— 组件会复制到你的项目中，便于完全掌控。