agents-ui

LiveKit Agents UI

shadcn ベースのコンポーネントを使用して、LiveKit の音声 AI エージェント向け React フロントエンドを構築します。

LiveKit MCP サーバーのツール

このスキルは LiveKit MCP サーバーと連携して動作し、最新の LiveKit ドキュメント、コード例、変更履歴に直接アクセスできます。このスキルの作成後に変更された可能性のある最新情報が必要な場合は、これらのツールを使用してください。

利用可能な MCP ツール：

• docs_search - LiveKit ドキュメントサイトを検索します
• get_pages - パスを指定して特定のドキュメントページを取得します
• get_changelog - LiveKit パッケージの最近のリリースと更新情報を取得します
• code_search - LiveKit リポジトリからコード例を検索します
• get_python_agent_example - 100 件以上の Python エージェント例を参照します

MCP ツールを使用する場合：

• 最新の API ドキュメントや機能の更新情報が必要な場合
• 最近の例やコードパターンを探す場合
• 最近のリリースで機能が追加されたかどうかを確認する場合
• ローカルのリファレンスに特定のトピックがない場合

ローカルのリファレンスを使用する場合：

• このスキルで扱う基本概念をすぐに確認したい場合
• オフラインで作業している場合、または一般的なパターンにすばやくアクセスしたい場合
• リファレンスにある情報で十分な場合

最適な利用体験のため、MCP ツールとローカルのリファレンスを併用してください。

リファレンス

必要に応じて、次のリソースを参照してください。

• ./references/livekit-overview.md -- LiveKit エコシステムの概要と、これらのスキルがどのように連携するか
• ./references/components.md -- すべてのコンポーネント API、props、使用例

前提条件

• Node.js >= 18
• React 19
• Tailwind CSS 4
• プロジェクトで shadcn/ui が初期化されていること

インストール

1. shadcn の設定に LiveKit レジストリを追加する

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');

音声エージェントの基本インターフェース

@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 />

音声ビジュアライザー

5 種類のビジュアライザースタイルがあります。

// 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 />

エージェントの状態

AgentSessionProvider は次の状態を追跡します。

• initializing - エージェントの起動中
• listening - エージェントがユーザー入力を待ち受け中
• thinking - エージェントが応答を処理または生成中
• speaking - エージェントが発話中

これらの状態を使用して、Agents UI コンポーネントと一緒にインストールされるローカルの useAgentState フックで 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 など）は必要ありません。UI には代わりに Agents UI コンポーネントを使用してください。

@livekit/components-react のフックを使用する

Agents UI では、useSession フックを使用するために @livekit/components-react が必要です。このパッケージの追加のフックを使用して、独自の動作を実装することもできます。これらのフックは AgentSessionProvider 内で動作します。

必須のフック：

• useSession — AgentSessionProvider に必要なセッションオブジェクトを作成します

独自の動作を実装するための追加フック：

• useAgent — ライフサイクルヘルパーを含むエージェントの全状態を取得します（useSession のセッションが必要です）
• useVoiceAssistant — エージェントの状態、トラック、文字起こしを取得します
• 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. TokenSource には useRef を使用してください — レンダリングのたびに再作成されないよう、TokenSource の作成は必ず useRef でラップしてください。
4. セッションを適切に開始・終了してください — useEffect 内で session.start() を呼び出し、クリーンアップ関数で session.end() を呼び出してください。
5. オーディオの権限を処理してください — ユーザーの操作が必要なブラウザーでは、StartAudioButton を使用してください。
6. Tailwind でカスタマイズしてください — スタイルを調整するには、className プロパティを使用してください。
7. ソースを直接変更してください — コンポーネントはプロジェクトにコピーされるため、完全に制御できます。