Skip to main content

Browser actions (BOA)

Archived SDK documentation

This page preserves the previous SDK documentation and its existing URL. The generated API reference was produced from SDK 0.1.5, source commit 4db9fbe925bf07a4b95e936a5bb172d6ab5820bb. Handbook behavior and compatibility claims below are historical descriptions, not a newly verified support guarantee. For the reviewed version-specific reference, see the SDK 0.1.5 overview.

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.