Skip to main content

Introduction

AaaS Pilot Kit SDK optimized specifically for React applications, providing React Hooks and component wrappers.

Features​

  • 🪝 React Hooks API - useAaaSPilotKit, useConversation, useConversationList, etc.
  • 🎯 Context Provider - AaaSPilotKitProvider follows React Context standard patterns, manages global state, enables cross-component state sharing and dependency injection, seamless integration
  • 📦 TypeScript Support - Complete type definitions
  • 🔄 State Management Integration - Supports Redux, Zustand, and other state management libraries
  • ⚡ Performance Optimization - Built-in rendering optimization strategies, automatically isolates external state changes, avoids unnecessary re-renders
  • 🎨 Event System - Simplified event listener interface

Quick Start​

Installation​

Use the public package @bdky/aaas-pilot-kit-react.

npm

$ npm install @bdky/aaas-pilot-kit-react

yarn

$ yarn add @bdky/aaas-pilot-kit-react

Basic Usage​

import {
    AaaSPilotKitProvider,
    useAaaSPilotKit,
    useAaaSPilotKitEvents,
    useConversationList
} from '@bdky/aaas-pilot-kit-react';
import {useRef} from 'react';

const options = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // agentConfig: Required if no custom agentService is provided
    agentConfig: {
        token: 'xxxx',
        robotId: 'xxxx'
    }
};

function App() {
    return (
        <AaaSPilotKitProvider options={options}>
            <Dashboard/>
        </AaaSPilotKitProvider>
    );
}

function Dashboard() {
    const {controller, isReady, isMuted, isRendering} = useAaaSPilotKit();
    const {conversationList} = useConversationList();
    const containerRef = useRef<HTMLDivElement>(null)

    useAaaSPilotKitEvents({
        onReady: () => console.log('Digital Employee ready'),
        onAsrMessage: payload => console.log('ASR:', payload.text)
    });

    useEffect(
        () => {
            // Ensure both controller and containerRef exist, then mount to initialize
            // ⚠️ Make sure to only mount once!!!
            // Note: React StrictMode and React 19 intentionally trigger useEffect twice in development mode
            // This may cause mount() to be called multiple times, generating warning messages
            if (controller && containerRef.current) {
                controller.mount(containerRef.current);
            }
        },
        [controller]
    );

    return (
        <section>
            <div>Status: {isReady ? 'Ready' : 'Initializing'}</div>
            <div>Muted: {isMuted ? 'Yes' : 'No'}</div>
            <div>Rendering: {isRendering ? 'In progress' : 'Idle'}</div>
            <div>Conversations: {conversationList.length}</div>
            <button onClick={() => controller?.input('Hello')}>Send message</button>
            <div ref={containerRef} style={{width: 400, height: 700}} />
        </section>
    );
}
React StrictMode Development Mode Reminder

In React StrictMode and React 19 development mode, useEffect will execute twice intentionally to help discover side effect issues. This may cause controller.mount() to be called multiple times, generating console warning messages. This is normal development mode behavior and will not occur in production environments.

To avoid development warnings, you can add a cleanup function in useEffect:

useEffect(
    () => {
        if (controller && containerRef.current) {
            controller.mount(containerRef.current);

            return () => {
                // Cleanup function to avoid repeated mounting
                controller.dispose();
            };
        }
    },
    [controller]
);

Or use ref to track mount state, ensuring only one mount:

const containerRef = useRef<HTMLDivElement>(null);
const mountedRef = useRef(false);

useEffect(
    () => {
        // Use ref to mark and avoid repeated mounting
        if (controller && containerRef.current && !mountedRef.current) {
            controller.mount(containerRef.current);
            mountedRef.current = true;
        }
    },
    [controller]
);

Core API​

Provider Component​

AaaSPilotKitProvider is the entry point for the entire React SDK, responsible for:

  • Creating and managing underlying controller instances
  • Providing global state sharing
  • Automatically handling lifecycle
<AaaSPilotKitProvider options={options}>
    {/* Your application components */}
</AaaSPilotKitProvider>

Core Hooks​

HookFunctionReturns
useAaaSPilotKitGet controller and state{controller, isReady, isMuted, isRendering, create, dispose}
useAaaSPilotKitEventsBind event listenersvoid
useConversationListGet conversation list{conversationList}
useConversationHandle single conversation{conversationContents}

Event Handling​

Simplified event listener interface:

useAaaSPilotKitEvents({
    onReady: () => console.log('Ready'),
    onAsrMessage: (payload) => console.log('ASR result:', payload.text),
    onError: (error) => console.error('Error:', error),
    onConversationChange: (payload) => updateUI(payload),
    // ...
});

Advanced Usage​

Custom AgentService​

When integrating a private Agent streaming API protocol, you can create a custom Agent service class by extending BaseAgentService:

// Pass custom AgentService
const options = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    agentService: CustomAgentService // Replaces agentConfig, at this point agentConfig can be omitted
};

function App() {
    return (
        <AaaSPilotKitProvider options={options}>
            <Dashboard />
        </AaaSPilotKitProvider>
    );
}

⚠️ Note: When using a custom agentService, the agentConfig configuration will not be available.

Detailed implementation guide: Custom AgentService Configuration

Integrating with State Management​

// Redux integration
function ReduxComponent() {
    const dispatch = useDispatch();

    useAaaSPilotKitEvents({
        onConversationAdd: (conversation) =>
            dispatch(addConversation(conversation))
    });
}

// Zustand integration
function ZustandComponent() {
    const addConversation = useStore(state => state.addConversation);

    useAaaSPilotKitEvents({
        onConversationAdd: addConversation
    });
}

Complete Example​

See Installation and Quick Start for complete usage examples.

Documentation Navigation​

  • Quick Start - Installation configuration and basic usage
  • Provider Context - Provider detailed configuration and advanced usage
  • Hooks API - Detailed reference for all Hooks
  • FAQ - Common questions and solutions

Technical Support​