buildNavaiAgent

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

async function buildNavaiAgent(
  options: BuildNavaiAgentOptions
): Promise<BuildNavaiAgentResult>

{ "ok": true, "path": "/profile" }

{ "ok": false, "error": "Unknown or disallowed route." }

{
  "ok": true,
  "function_name": "search",
  "source": "frontend",
  "result": { /* function result */ }
}

{
  "ok": false,
  "function_name": "unknown_fn",
  "error": "Unknown or disallowed function.",
  "available_functions": ["search", "get_user"]
}

// Instead of:
execute_app_function("search", { payload: { args: ["query"] } })

// Can use:
search({ payload: { args: ["query"] } })

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

const { agent, warnings } = await buildNavaiAgent({
  navigate: (path) => router.push(path),
  routes: [
    { name: 'home', path: '/', description: 'Home page' },
    { name: 'profile', path: '/profile', description: 'User profile' }
  ]
});

// Log any warnings
warnings.forEach(warning => console.warn(warning));

// Use agent with RealtimeSession
import { RealtimeSession } from '@openai/agents/realtime';
const session = new RealtimeSession(agent);
await session.connect({ apiKey: 'your-api-key' });

const { agent } = await buildNavaiAgent({
  navigate,
  routes,
  functionModuleLoaders: {
    './functions/search.ts': () => import('./functions/search'),
    './functions/profile.ts': () => import('./functions/profile')
  }
});

const { agent } = await buildNavaiAgent({
  navigate,
  routes,
  backendFunctions: [
    {
      name: 'send_email',
      description: 'Send an email',
      source: 'backend'
    },
    {
      name: 'create_order',
      description: 'Create a new order',
      source: 'backend'
    }
  ],
  executeBackendFunction: async ({ functionName, payload }) => {
    const response = await fetch('/api/functions/execute', {
      method: 'POST',
      body: JSON.stringify({ functionName, payload })
    });
    return response.json();
  }
});

const { agent } = await buildNavaiAgent({
  navigate,
  routes,
  agentName: 'My App Assistant',
  baseInstructions: `You are a helpful assistant for MyApp. 
Be friendly and concise. 
Always confirm before executing sensitive actions.`
});

const { agent, warnings } = await buildNavaiAgent({
  navigate: (path) => router.push(path),
  routes: [
    {
      name: 'home',
      path: '/',
      description: 'Home page',
      synonyms: ['main', 'dashboard']
    },
    {
      name: 'search',
      path: '/search',
      description: 'Search page'
    }
  ],
  functionModuleLoaders: {
    './functions/search.ts': () => import('./functions/search')
  },
  backendFunctions: [
    {
      name: 'send_notification',
      description: 'Send a push notification',
      source: 'backend'
    }
  ],
  executeBackendFunction: async ({ functionName, payload }) => {
    const response = await backendClient.executeFunction({
      functionName,
      payload
    });
    return response;
  },
  agentName: 'MyApp Voice',
  baseInstructions: 'You are a voice assistant for MyApp.'
});

// Handle warnings
if (warnings.length > 0) {
  console.warn('Agent warnings:', warnings);
}

// Connect agent
const session = new RealtimeSession(agent);
await session.connect({ apiKey });

You are a voice assistant embedded in a web app.
Allowed routes:
- home (/) aliases: main, dashboard
- profile (/profile)
Allowed app functions:
- search: Search for content
- send_notification: Send a push notification
Rules:
- If user asks to go/open a section, always call navigate_to.
- If user asks to run an internal action, call execute_app_function or the matching direct function tool.
- Always include payload in execute_app_function. Use null when no arguments are needed.
- For execute_app_function, pass arguments using payload.args (array).
- For class methods, pass payload.constructorArgs and payload.methodArgs.
- Never invent routes or function names that are not listed.
- If destination/action is unclear, ask a brief clarifying question.

// Backend function conflicts with frontend
"[navai] Ignored backend function \"search\": name conflicts with a frontend function."

// Duplicate backend functions
"[navai] Ignored duplicated backend function \"send_email\"."

// Reserved name conflict
"[navai] Function \"navigate_to\" is available only via execute_app_function because its name conflicts with a built-in tool."

// Invalid tool name
"[navai] Function \"my function\" is available only via execute_app_function because its name is not a valid tool id."

// Duplicate after normalization
"[navai] Renamed duplicated function \"search\" to \"search_2\"."

{
  "ok": false,
  "function_name": "search",
  "error": "Function execution failed.",
  "details": "Database connection timeout"
}

// packages/voice-frontend/src/agent.ts:11-24

export type NavaiBackendFunctionDefinition = {
  name: string;
  description?: string;
  source?: string;
};

export type ExecuteNavaiBackendFunctionInput = {
  functionName: string;
  payload: Record<string, unknown> | null;
};

export type ExecuteNavaiBackendFunction = (
  input: ExecuteNavaiBackendFunctionInput
) => Promise<unknown> | unknown;

export type BuildNavaiAgentOptions = NavaiFunctionContext & {
  routes: NavaiRoute[];
  functionModuleLoaders?: NavaiFunctionModuleLoaders;
  backendFunctions?: NavaiBackendFunctionDefinition[];
  executeBackendFunction?: ExecuteNavaiBackendFunction;
  agentName?: string;
  baseInstructions?: string;
};

export type BuildNavaiAgentResult = {
  agent: RealtimeAgent;
  warnings: string[];
};