@bymos/agentkit-sdk

Embeddable AI chat widget for AgentForge. Add a fully-featured, themeable chat widget to any website or app — via a <script> tag or npm.

Installation

npm install @bymos/agentkit-sdk
# or
pnpm add @bymos/agentkit-sdk

Peer dependency: preact@^10.0.0

Quick start

CDN (no build step)

<script src="https://unpkg.com/@bymos/[email protected]/agentkit-widget.iife.js"></script>
<script>
  window.AgentKit.init({
    agentId: 'your-agent-id',
    tenantId: 'your-tenant-id',
    apiBaseUrl: 'https://api-agentforge.bymos.dev',
    title: 'Support',
    greeting: 'Hi! How can I help?',
  });
</script>

npm (ESM / CJS)

import { init, renderWidget, buildWidgetCSS, normalizeConfig } from '@bymos/agentkit-sdk';

const config = {
  agentId: 'your-agent-id',
  tenantId: 'your-tenant-id',
  apiBaseUrl: 'https://api-agentforge.bymos.dev',
};
const widget = init(config, renderWidget, buildWidgetCSS(normalizeConfig(config)));

widget.on('message:received', (msg) => console.log(msg.content));

Configuration

type AgentKitWidgetConfig = {
  // Required
  agentId: string; // Agent ID from your AgentForge dashboard
  tenantId: string; // Tenant ID from your AgentForge dashboard
  apiBaseUrl: string; // Base URL of your AgentForge API

  // Identity (optional)
  userId?: string;
  authUserId?: string; // Your authenticated user ID — links widget conversations to users in your app (highest-priority contact identifier)
  name?: string;
  email?: string;
  sessionId?: string; // Resume a conversation across tabs/page loads (within a tab, sessions are automatic)

  // Display (optional)
  mode?: 'floating' | 'inline'; // Default: 'floating'
  title?: string;
  greeting?: string;
  avatarUrl?: string;
  subtitle?: string;
  privacyPolicyUrl?: string;

  // Behaviour (optional)
  streaming?: boolean; // Default: true
  metadata?: Record<string, unknown>; // Sent with every message

  // Theming (optional)
  theme?: {
    mode?: 'light' | 'dark' | 'system'; // Default: 'light'
    accentColor?: string; // Default: '#6366f1'
    fontFamily?: string;
    borderRadius?: string; // Default: '12px'
  };
};

At init time the widget fetches any widget config set for your agent in the AgentForge dashboard (title, greeting, avatar, etc.) and uses it as defaults. Any values you pass here override the dashboard config.

Widget instance API

Both init() and mount() return a WidgetInstance:

widget.open();
widget.close();
widget.toggle();
widget.sendMessage('Hello!');
widget.reset(); // Clear conversation and show greeting again
widget.destroy();
widget.getState(); // → WidgetState
widget.on(event, fn);
widget.off(event, fn);

Events

| Event | Payload | | ---------------------- | ------------------------ | | ready | WidgetState | | open / close | — | | message:sent | WidgetMessage | | message:received | WidgetMessage | | message:error | { error, message } | | conversation:started | { sessionId } | | stream:start | — | | stream:delta | { delta, accumulated } | | stream:end | { content } | | reset | — | | destroy | — |

CDN global API (window.AgentKit)

| Method | Description | | ------------------------ | ---------------------------------------------------- | | init(config) | Create a floating widget anchored to document.body | | mount(element, config) | Mount a widget inline inside a DOM element | | destroy(id?) | Destroy widget by ID, or all widgets if no ID given |

Inline mount example

<div id="chat"></div>
<script src="https://unpkg.com/@bymos/[email protected]/agentkit-widget.iife.js"></script>
<script>
  window.AgentKit.mount(document.getElementById('chat'), {
    agentId: 'your-agent-id',
    tenantId: 'your-tenant-id',
    apiBaseUrl: 'https://api-agentforge.bymos.dev',
    mode: 'inline',
  });
</script>

npm exports

// Lifecycle
import { init, mount, destroyWidget, listWidgets, createWidget } from '@bymos/agentkit-sdk';

// Config
import { normalizeConfig } from '@bymos/agentkit-sdk';

// Session
import { getSessionId, setSessionId, clearSession } from '@bymos/agentkit-sdk';

// UI (requires preact peer dep)
import { renderWidget, buildWidgetCSS, buildThemeVars } from '@bymos/agentkit-sdk';

// Lower-level
import { ApiClient, streamChat, EventEmitter } from '@bymos/agentkit-sdk';
import {
  createShadowHost,
  createFloatingContainer,
  prepareInlineContainer,
} from '@bymos/agentkit-sdk';

// Types
import type {
  AgentKitWidgetConfig,
  NormalizedWidgetConfig,
  WidgetInstance,
  WidgetState,
  WidgetMessage,
  WidgetEventMap,
  RenderFn,
} from '@bymos/agentkit-sdk';

Session management

Within a browser tab, sessions are automatic — the SDK reads and writes sessionStorage keyed by agentId with no configuration needed. Sessions are cleared when the tab closes.

To persist a conversation across tabs or page reloads, save and restore the session ID yourself:

widget.on('conversation:started', ({ sessionId }) => {
  localStorage.setItem('chat-session', sessionId);
});

// Later, on next load:
const widget = window.AgentKit.init({
  agentId: 'your-agent-id',
  tenantId: 'your-tenant-id',
  apiBaseUrl: '...',
  sessionId: localStorage.getItem('chat-session') ?? undefined,
});

Theming

The widget renders inside a Shadow DOM to prevent CSS conflicts with your page. Use the theme config to customise it:

window.AgentKit.init({
  agentId: 'your-agent-id',
  apiBaseUrl: '...',
  theme: {
    mode: 'dark',
    accentColor: '#ec4899',
    fontFamily: "'Inter', sans-serif",
    borderRadius: '8px',
  },
});

Requirements

• Node.js ≥ 18 (for npm usage)
• Modern browser with Shadow DOM support