跳至主要内容

Web 和移动前端

通过 Web 或移动应用让您的 Agent 栩栩如生。

概述

LiveKit Agents 已经准备好与您首选的前端平台集成,使用 LiveKit SDK for JavaScript, Swift, Android, Flutter, React Native 等。您的 Agent 可以通过 LiveKit WebRTC 与您的前端进行通信,从而提供快速可靠的实时连接。

例如,一个简单的语音 Agent 订阅用户的麦克风轨道并发布自己的轨道。 文本转录 也作为文本流可用。 具有视觉功能的更复杂的 Agent 可以订阅从用户摄像头或共享屏幕发布的视频轨道。 Agent 还可以发布自己的视频以实现虚拟头像或其他功能。

在所有这些情况下,LiveKit SDK 都是生产级的并且易于使用,因此您可以构建有用且高级的 Agent,而无需担心实时媒体传输的复杂性。 本主题包含构建高质量 Agent 前端所需的资源和技巧。

入门应用

LiveKit 建议使用以下入门应用之一,以便在您首选的平台上快速启动。 每个应用都是开源的,采用 MIT 许可证,因此您可以自由地根据自己的需求进行修改。 移动应用需要托管令牌服务器,但包含一个 LiveKit Cloud 沙箱 用于开发目的。

https://:3000

媒体和文本

要了解有关实时媒体和文本流的更多信息,请参阅以下文档。

数据共享

要共享图像、文件或任何其他类型的数据在您的前端和您的代理之间,您可以使用以下功能。

状态和控制

在某些情况下,您的代理和您的前端代码可能需要状态和配置的自定义集成,以满足您的应用程序的要求。 在这些情况下,LiveKit 实时状态和数据功能可用于创建紧密耦合和响应迅速的体验。

AgentSession 会自动管理 lk.agent.state 参与者属性,以包含以下适当的字符串值:initializinglisteningthinkingspeaking

音频可视化

适用于 React、SwiftUI、Android Compose 和 Flutter 的 LiveKit 组件 SDK 包含音频可视化组件,可用于为您的语音代理在您的应用程序中提供视觉呈现。

有关完整示例,请参阅上面列出的示例应用程序。 以下文档是使用这些组件的快速指南

安装 React 组件样式 包来使用 useVoiceAssistant hook 和 BarVisualizer。这些组件可以在 LiveKitRoomRoomContext.Provider 中自动工作。

另请参阅 VoiceAssistantControlBar,它为语音代理应用程序提供一组简单的常用 UI 控制。

"use client";
import "@livekit/components-styles";
import {
useVoiceAssistant,
BarVisualizer,
} from "@livekit/components-react";
export default function SimpleVoiceAssistant() {
// Get the agent's audio track and current state
const { state, audioTrack } = useVoiceAssistant();
return (
<div className="h-80">
<BarVisualizer state={state} barCount={5} trackRef={audioTrack} style={{}} />
<p className="text-center">{state}</p>
</div>
);
}

首先从 https://github.com/livekit/components-swift 安装组件包。

然后您可以使用 AgentBarAudioVisualizer 视图来显示代理的音频和状态

struct AgentView: View {
// Load the room from the environment
@EnvironmentObject private var room: Room
// Find the first agent participant in the room
private var agentParticipant: RemoteParticipant? {
for participant in room.remoteParticipants.values {
if participant.kind == .agent {
return participant
}
}
return nil
}
// Reads the agent state property
private var agentState: AgentState {
agentParticipant?.agentState ?? .initializing
}
var body: some View {
AgentBarAudioVisualizer(audioTrack: participant.firstAudioTrack, agentState: agentState, barColor: .primary, barCount: 5)
.id(participant.firstAudioTrack?.id)
}
}

首先从 https://github.com/livekit/components-android 安装组件包。

然后您可以使用 rememberVoiceAssistantVoiceAssistantBarVisualizer composables 来显示可视化器,假设您位于 RoomScope composable 中。

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import io.livekit.android.compose.state.rememberVoiceAssistant
import io.livekit.android.compose.ui.audio.VoiceAssistantBarVisualizer
@Composable
fun AgentAudioVisualizer(modifier: Modifier = Modifier) {
// Get the voice assistant instance
val voiceAssistant = rememberVoiceAssistant()
// Display the audio visualization
VoiceAssistantBarVisualizer(
voiceAssistant = voiceAssistant,
modifier = modifier
.padding(8.dp)
.fillMaxWidth()
)
}

首先从 https://github.com/livekit/components-flutter 安装组件包。

flutter pub add livekit_components

在创建 Room 时启用音频可视化。

// Enable audio visualization when creating the Room
final room = Room(roomOptions: const RoomOptions(enableVisualizer: true));

然后您可以使用 SoundWaveformWidget 来显示代理的音频可视化,假设您正在使用 RoomContext

import 'package:flutter/material.dart';
import 'package:livekit_client/livekit_client.dart';
import 'package:livekit_components/livekit_components.dart' hide ParticipantKind;
import 'package:provider/provider.dart';
/// Shows a simple audio visualizer for an agent participant
class AgentView extends StatelessWidget {
const AgentView({super.key});
Widget build(BuildContext context) {
return Consumer<RoomContext>(
builder: (context, roomContext, child) {
// Find the agent participant in the room
final agentParticipant = roomContext.room.remoteParticipants.values
.where((p) => p.kind == ParticipantKind.AGENT)
.firstOrNull;
if (agentParticipant == null) {
return const SizedBox.shrink();
}
// Get the agent's audio track for visualization
final audioTrack = agentParticipant.audioTrackPublications
.firstOrNull?.track as AudioTrack?;
if (audioTrack == null) {
return const SizedBox.shrink();
}
// Show the waveform visualization
return SoundWaveformWidget(
audioTrack: audioTrack,
options: AudioVisualizerOptions(
width: 32,
minHeight: 32,
maxHeight: 256,
color: Theme.of(context).colorScheme.primary,
count: 7,
),
);
},
);
}
}

身份验证

LiveKit SDK 需要一个 token 才能连接到房间。在 Web 应用程序中,您通常可以将一个简单的 token 端点作为应用程序的一部分包含在内。对于移动应用程序,您需要一个单独的 token 服务器

虚拟头像

您的前端可以使用来自受支持提供商的虚拟头像来包含代理的视频表示形式。LiveKit 在所有受支持的平台上都提供对视频渲染的完全支持。 入门应用程序 包含对虚拟头像的支持。有关更多信息和受支持提供商的列表,请参阅文档

虚拟头像

使用虚拟头像在您的应用程序中为您的代理提供视觉呈现。

响应式提示

本节包含一些建议,以使您的应用程序对用户感觉更具响应性。

最小化连接时间

要将您的用户连接到您的代理,必须执行以下步骤

  1. 获取访问令牌。
  2. 用户连接到房间。
  3. 调度代理进程。
  4. 代理连接到房间。
  5. 用户和代理发布并订阅彼此的媒体轨道。

如果按顺序完成,则完成此操作最多需要几秒钟。您可以通过消除或并行化这些步骤来减少此时间。

选项 1:“预热”令牌

在这种情况下,您的应用程序将在用户登录时生成一个具有较长过期时间的令牌。当您需要连接到房间时,令牌已在您的前端可用。

选项 2:在生成令牌期间调度代理

在这种情况下,您的应用程序将乐观地创建房间并在生成 token 的同时调度 agent,使用 显式 agent 调度。这允许用户和 agent 同时连接到房间。

连接指示器

通过将各种事件链接到用户仅有的一个或两个状态指示器,而不是大量的离散步骤和 UI 更改,使您的应用程序感觉更具响应性,即使连接速度较慢。请参阅 事件处理 文档,了解有关如何监控连接状态和其他事件的更多信息。

如果您的 agent 连接失败,您应该通知用户并允许他们重试,而不是让他们对着空房间说话。

  • 房间连接:在大多数 SDK 中,可以等待 room.connect 方法,并且大多数 SDK 也提供 room.connectionState 属性。还要监控 Disconnected 事件,以了解连接何时丢失。
  • Agent 存在性:监控 ParticipantConnected 事件,其中 participant.kind === ParticipantKind.AGENT
  • Agent 状态:访问 agent 的状态(initializinglisteningthinkingspeaking
  • Track 订阅:监听 TrackSubscribed 事件,以了解您的媒体何时被订阅。

效果

您应该使用音效、触觉反馈和视觉效果,使您的 agent 感觉更具响应性。这在长时间的思考状态期间尤其重要(例如,在执行外部查找或使用工具时)。可视化工具 包括基本的“思考”状态指示,并允许用户注意到他们的音频何时无法工作。对于更高级的效果,请使用 状态和控制 功能,以在您的前端触发效果。