Rename agent state property to lk.agent.state (#976)

Co-authored-by: lukasIO <[email protected]>

.changeset/cuddly-beers-cry.md

@@ -0,0 +1,6 @@
+---
+"@livekit/components-react": minor
+"@livekit/component-example-next": patch
+---
+
+Update agent state property name to `lk.agent.state`

packages/react/etc/components-react.api.md

@@ -37,6 +37,9 @@ import { TrackPublishOptions } from 'livekit-client';
 import type { TranscriptionSegment } from 'livekit-client';
 import type { VideoCaptureOptions } from 'livekit-client';
 
+// @beta (undocumented)
+export type AgentState = 'disconnected' | 'connecting' | 'initializing' | 'listening' | 'thinking' | 'speaking';
+
 // @public (undocumented)
 export interface AllowAudioPlaybackProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
     // (undocumented)
@@ -103,7 +106,7 @@ export interface BarVisualizerProps extends React_2.HTMLProps<HTMLDivElement> {
     children?: React_2.ReactNode;
     // (undocumented)
     options?: BarVisualizerOptions;
-    state?: VoiceAssistantState;
+    state?: AgentState;
     // (undocumented)
     trackRef?: TrackReferenceOrPlaceholder;
 }
@@ -1276,7 +1279,7 @@ export interface VoiceAssistant {
     // (undocumented)
     audioTrack: TrackReference | undefined;
     // (undocumented)
-    state: VoiceAssistantState;
+    state: AgentState;
 }
 
 // @beta (undocumented)
@@ -1300,9 +1303,6 @@ export interface VoiceAssistantControlBarProps extends React_2.HTMLAttributes<HT
     saveUserChoices?: boolean;
 }
 
-// @beta (undocumented)
-export type VoiceAssistantState = 'disconnected' | 'connecting' | 'initializing' | 'listening' | 'thinking' | 'speaking';
-
 // @public (undocumented)
 export type WidgetState = {
     showChat: boolean;

packages/react/src/components/participant/BarVisualizer.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { useBarAnimator } from './animators/useBarAnimator';
-import { useMultibandTrackVolume, type VoiceAssistantState } from '../../hooks';
+import { useMultibandTrackVolume, type AgentState } from '../../hooks';
 import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
 import { useMaybeTrackRefContext } from '../../context';
 import { cloneSingleChild, mergeProps } from '../../utils';
@@ -20,7 +20,7 @@ export type BarVisualizerOptions = {
  */
 export interface BarVisualizerProps extends React.HTMLProps<HTMLDivElement> {
   /** If set, the visualizer will transition between different voice assistant states */
-  state?: VoiceAssistantState;
+  state?: AgentState;
   /** Number of bars that show up in the visualizer */
   barCount?: number;
   trackRef?: TrackReferenceOrPlaceholder;
@@ -29,14 +29,14 @@ export interface BarVisualizerProps extends React.HTMLProps<HTMLDivElement> {
   children?: React.ReactNode;
 }
 
-const sequencerIntervals = new Map<VoiceAssistantState, number>([
+const sequencerIntervals = new Map<AgentState, number>([
   ['connecting', 25 * 15],
   ['listening', 500],
   ['thinking', 150],
 ]);
 
 const getSequencerInterval = (
-  state: VoiceAssistantState | undefined,
+  state: AgentState | undefined,
   barCount: number,
 ): number | undefined => {
   if (state === undefined) {

packages/react/src/components/participant/animators/useBarAnimator.ts

@@ -1,10 +1,10 @@
 import { useEffect, useRef, useState } from 'react';
 import { generateConnectingSequenceBar } from '../animationSequences/connectingSequence';
 import { generateListeningSequenceBar } from '../animationSequences/listeningSequence';
-import type { VoiceAssistantState } from '../../../hooks';
+import type { AgentState } from '../../../hooks';
 
 export const useBarAnimator = (
-  state: VoiceAssistantState | undefined,
+  state: AgentState | undefined,
   columns: number,
   interval: number,
 ): number[] => {

packages/react/src/hooks/useVoiceAssistant.ts

@@ -11,7 +11,7 @@ import { useParticipantAttributes } from './useParticipantAttributes';
 /**
  * @beta
  */
-export type VoiceAssistantState =
+export type AgentState =
   | 'disconnected'
   | 'connecting'
   | 'initializing'
@@ -24,19 +24,17 @@ export type VoiceAssistantState =
  */
 export interface VoiceAssistant {
   agent: RemoteParticipant | undefined;
-  state: VoiceAssistantState;
+  state: AgentState;
   audioTrack: TrackReference | undefined;
   agentTranscriptions: ReceivedTranscriptionSegment[];
   agentAttributes: RemoteParticipant['attributes'] | undefined;
 }
 
-const state_attribute = 'voice_assistant.state';
+const state_attribute = 'lk.agent.state';
 
 /**
  * This hook looks for the first agent-participant in the room.
- * It assumes that the agent participant is based on the LiveKit VoiceAssistant API and
- * returns the most commonly used state vars when interacting with a VoiceAssistant.
- * @remarks This hook requires a voice assistant agent running with livekit-agents \>= 0.8.11
+ * @remarks This hook requires an agent running with livekit-agents \>= 0.8.11
  * @example
  * ```tsx
  * const { state, audioTrack, agentTranscriptions, agentAttributes } = useVoiceAssistant();
@@ -50,7 +48,7 @@ export function useVoiceAssistant(): VoiceAssistant {
   const connectionState = useConnectionState();
   const { attributes } = useParticipantAttributes({ participant: agent });
 
-  const state: VoiceAssistantState = React.useMemo(() => {
+  const state: AgentState = React.useMemo(() => {
     if (connectionState === ConnectionState.Disconnected) {
       return 'disconnected';
     } else if (
@@ -60,7 +58,7 @@ export function useVoiceAssistant(): VoiceAssistant {
     ) {
       return 'connecting';
     } else {
-      return attributes[state_attribute] as VoiceAssistantState;
+      return attributes[state_attribute] as AgentState;
     }
   }, [attributes, agent, connectionState]);
 

packages/react/src/prefabs/index.ts

@@ -4,4 +4,8 @@ export { VideoConference, type VideoConferenceProps } from './VideoConference';
 export { ControlBar, type ControlBarProps, type ControlBarControls } from './ControlBar';
 export { MediaDeviceMenu, type MediaDeviceMenuProps } from './MediaDeviceMenu';
 export { AudioConference, type AudioConferenceProps } from './AudioConference';
-export * from './VoiceAssistantControlBar';
+export {
+  VoiceAssistantControlBar,
+  type VoiceAssistantControlBarProps,
+  type VoiceAssistantControlBarControls,
+} from './VoiceAssistantControlBar';