daba-agent

Embeddable voice AI assistant widget for dabalabs projects. Drop it into any site and visitors can press Ctrl+Space, talk in any language, and get a spoken reply — the agent can also read the page, fill out and submit forms, and navigate to other pages on request.

Works natively in Plain HTML, React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, and any modern JavaScript stack.

Install

npm install dabalabs-agent

Quick Start

1. Web Component (<daba-agent>) — Works in Any JS Framework / HTML

Simply import dabalabs-agent (or dabalabs-agent/custom-element) and use <daba-agent> directly in your HTML or JSX/Vue/Svelte template:

<daba-agent
  project-id="YOUR_PROJECT_ID"
  api-key="YOUR_API_KEY"
  position="bottom-right"
></daba-agent>

Plain HTML / Script Tag

<script src="https://unpkg.com/dabalabs-agent/dist/daba-agent.min.js"></script>
<daba-agent project-id="YOUR_PROJECT_ID" api-key="YOUR_API_KEY"></daba-agent>

Vue 3 / Nuxt 3

<script setup>
import 'dabalabs-agent/custom-element';
</script>

<template>
  <daba-agent
    project-id="YOUR_PROJECT_ID"
    api-key="YOUR_API_KEY"
    position="bottom-right"
  />
</template>

Svelte / SvelteKit / Astro

<script>
  import 'dabalabs-agent/custom-element';
</script>

<daba-agent project-id="YOUR_PROJECT_ID" api-key="YOUR_API_KEY" />

2. React Component (<DabaAgent />) — React & Next.js

"use client";

import { DabaAgent } from "dabalabs-agent/react";

export function App() {
  return (
    <DabaAgent
      projectId="YOUR_PROJECT_ID"
      apiKey="YOUR_API_KEY"
      position="bottom-right"
      onStatusChange={(status) => console.log("Agent status:", status)}
    />
  );
}

3. Programmatic Class API (new DabaAgent())

import { DabaAgent } from "dabalabs-agent";

const agent = new DabaAgent({
  projectId: "YOUR_PROJECT_ID",
  apiKey: "YOUR_API_KEY",
  position: "bottom-right",
});

Get a project ID and API key from the Developer section of your dabalabs dashboard — the same API key used for the dabalabs video player works here too.

Custom Events on Web Component (<daba-agent>)

The <daba-agent> element dispatches native DOM Custom Events:

• daba-status-change (e.detail.status) — Fired when status changes (idle, connecting, listening, thinking, speaking)
• daba-transcript (e.detail: { role, text, isFinal }) — Fired on user or agent transcript deltas
• daba-error (e.detail.error) — Fired on network or session errors

Example:

const agentEl = document.querySelector('daba-agent');
agentEl.addEventListener('daba-status-change', (e) => {
  console.log('Status:', e.detail.status);
});

API keys are publishable

The API key is meant to sit in your site's frontend source, the same trust model as a Stripe.js or Google Maps JS key. Server-side, it's restricted to the exact origins you list when you create it, and to the one agent project it was scoped to. It can't create, modify, or delete anything, and it can be revoked instantly from your dashboard.

Options

| Option / Attribute | Type | Description | | --- | --- | --- | | projectId / project-id | string | Your agent project ID from the dashboard | | apiKey / api-key | string | Your publishable API key | | position | "bottom-right" \| "bottom-left" \| "top-right" \| "top-left" | Corner of the viewport for the default badge (default: "bottom-right"). | | accentColor / accent-color | string | Accent color hex for the badge's active-state indicator | | hotkey | string \| null | Keyboard shortcut to toggle the agent (default: "ctrl+space"). Pass null to disable. | | gatewayUrl / gateway-url | string (optional) | Base URL of the gateway (defaults to "https://api.dabalabs.com") | | onStatusChange | (status: DabaAgentStatus) => void | Fired as the agent moves through status lifecycle (React / JS API) | | onTranscript | (role: "user" \| "agent", text: string, isFinal: boolean) => void | Fired with transcript deltas (React / JS API) | | onError | (error: DabaError) => void | Fired on connection or session errors (React / JS API) |

Methods (on agent instance or element.dabaAgent)

• agent.toggle() — start or stop a session
• agent.destroy() — tear down the session, remove the badge, and detach all listeners
• agent.currentStatus — the current DabaAgentStatus
• agent.isActive — whether a session is currently running

What the agent can do

• Talk. Full duplex voice in and out over a single realtime connection — no separate transcription/TTS round trip.
• Read the page. On session start, the agent is given the page title, visible text, navigable links, and form fields, so it can answer questions about the page and knows what it can act on.
• Fill out and submit forms. The agent fills fields by label, then confirms with the visitor before submitting — it never submits silently. Password, card, and other sensitive-looking fields are refused outright, whether marked or not.
• Navigate. Ask it to go to another page and it will, resuming the same conversation on the other side rather than starting over.

Security guards

• data-daba-agent-ignore on any element (or a container) excludes it and its subtree from page reading and from form-filling.
• data-daba-agent-restricted on <html>, or <meta name="daba-agent-restricted"> in <head>, opts an entire page out — the agent won't read the page or start a session there at all. Use this on account, billing, or checkout pages.
• Password fields, payment fields (autocomplete="cc-*"), and labels that read like a PIN or security code are never filled or spoken back, regardless of how the model was asked.

Browser support

Requires WebSocket, AudioContext, and getUserMedia — every evergreen browser. The widget itself renders no UI beyond the floating badge, so it has no layout dependencies on the host page.

License

MIT