Frontend Package Overview

​

Introduction

​

Installation

npm install @navai/voice-frontend

​

Core Features

​

Voice Agent Integration

• Real-time connection management
• Backend authentication and function loading
• Route-based navigation
• Frontend and backend function execution
• Error handling and state management

​

Agent Building

• Navigation tools for route management
• Function execution capabilities
• Dynamic tool registration
• Conflict detection and warnings

​

Backend Client

• Creating ephemeral client secrets
• Listing available backend functions
• Executing backend functions

​

Quick Start

import { useWebVoiceAgent } from '@navai/voice-frontend';

function VoiceButton() {
  const { status, start, stop } = useWebVoiceAgent({
    navigate: (path) => router.push(path),
    moduleLoaders: {
      './functions/search.ts': () => import('./functions/search')
    },
    defaultRoutes: [
      { name: 'home', path: '/', description: 'Home page' },
      { name: 'profile', path: '/profile', description: 'User profile' }
    ]
  });

  return (
    <button onClick={status === 'connected' ? stop : start}>
      {status === 'connected' ? 'Stop' : 'Start'} Voice
    </button>
  );
}

​

Package Exports

​

Hooks

• useWebVoiceAgent - Main React hook for voice agent integration

​

Agent Building

• buildNavaiAgent - Create configured Realtime agent
• BuildNavaiAgentOptions - Agent configuration options
• BuildNavaiAgentResult - Agent build result with warnings

​

Backend Client

• createNavaiBackendClient - Create HTTP client for backend
• NavaiBackendClient - Backend client interface
• CreateNavaiBackendClientOptions - Client configuration

​

Functions

• loadNavaiFunctions - Load and register frontend functions
• NavaiFunctionDefinition - Function definition type
• NavaiFunctionsRegistry - Function registry type
• NavaiFunctionModuleLoaders - Module loader map

​

Routes

• resolveNavaiRoute - Resolve route name/path to path
• getNavaiRoutePromptLines - Generate route prompt text
• NavaiRoute - Route definition type

​

Types

​

Architecture

┌─────────────────────┐
│  useWebVoiceAgent   │  React Hook
└──────────┬──────────┘
           │
     ┌─────┴─────┐
     │           │
┌────▼─────┐  ┌──▼────────────┐
│  Agent   │  │ Backend Client│
│ Builder  │  │               │
└────┬─────┘  └──┬────────────┘
     │           │
     │      ┌────▼─────┐
     │      │ Functions│
     │      │  List    │
     │      └────┬─────┘
     │           │
┌────▼───────────▼───┐
│  Realtime Session  │
└────────────────────┘

​

Next Steps

• useWebVoiceAgent Hook - Complete hook reference
• buildNavaiAgent - Agent building API
• Backend Client - HTTP client reference
• Functions - Function loading and execution
• Routes - Route resolution
• Types - TypeScript types