Skip to main content

Browser actions (BOA)

When the AI tells the browser to do something — navigate, show_alert, copy_to_clipboard, set_storage, or a custom flow — the SDK delivers it via the session's onAction callback.

Standard handler​

executeBrowserAction covers the common actions out of the box:

import {executeBrowserAction} from '@ki-kombinat/delphi-client-js-sdk';

const session = await delphi.openSession({endpointId, mode: 'voice_conversation'});

session.updateOptions({
  onAction: (action) =>
    executeBrowserAction(action, {
      onNavigate: (path) => router.push(path),
      customHandlers: {
        fill_invoice_form: async (params) => ({
          success: true,
          data: await fillInvoice(params),
        }),
      },
      onUnknownAction: (action) => ({
        success: false,
        error: `No handler for ${action.name}`,
      }),
    }),
});

Standard action names​

import {StandardActions} from '@ki-kombinat/delphi-client-js-sdk';

StandardActions.NAVIGATE; // 'navigate'
StandardActions.NAVIGATE_CURRENT; // 'navigate_current'
StandardActions.SHOW_ALERT; // 'show_alert'
StandardActions.COPY_TO_CLIPBOARD; // 'copy_to_clipboard'
StandardActions.SCROLL_TO; // 'scroll_to'
StandardActions.SET_STORAGE; // 'set_storage'
StandardActions.GET_STORAGE; // 'get_storage'
StandardActions.CUSTOM; // 'custom'

executeBrowserAction handles the standard names internally. You only need to provide the navigation router and any app-specific custom handlers.

Async results​

For actions whose result the AI must wait on, return a Promise<ActionResult> from the handler or call session.sendAsyncActionResult later:

session.updateOptions({
  onAction: async (action) => {
    if (action.name === 'fill_invoice_form') {
      // Long-running flow with progress.
      session.sendActionProgress(action.actionId, {status: 'in_progress', percent: 25});
      const data = await fillInvoice(action.params);
      session.sendAsyncActionResult(action.actionId, true, {data});
      return; // returning void avoids double-resulting
    }
  },
});

React​

Use useBrowserAction instead of wiring executeBrowserAction manually — it memoizes the handler and threads sensible defaults. See React bindings.

When to use browser_actions mode​

The browser_actions session mode is useful when the AI doesn't need to converse — your app just needs a server-issued action channel (for example, an admin tool that listens for set_storage instructions from a workflow). For interactive flows, prefer voice_conversation, audio_playback, or text and let actions piggyback on those sessions.