Installation

The Agentic Trust widget is available as a hosted script for any HTML site, an npm package (@agentictrust/ui) for React apps, and works with Next.js App Router out of the box. It renders a chat interface on your site, connects to your project’s API, and streams AI responses in real time.

Install

Script tag
React
Next.js

Include the widget script and initialize it — no build step required.1. Add the script

<script src="https://platform.agentictrust.com/widget.js"></script>

2. Initialize

<script>
  AgenticTrust.initAsync({
    apiUrl: "https://platform.agentictrust.com/api/v1",
    apiKey: "lum_pk_your_api_key"
  });
</script>

<script>
  AgenticTrust.init({
    apiUrl: "https://platform.agentictrust.com/api/v1",
    apiKey: "lum_pk_your_api_key"
  });
</script>

initAsync fetches the widget configuration from the server before rendering, so the widget reflects your dashboard settings (colors, position, branding). init uses defaults and renders immediately.3. VerifyReload your page. A chat bubble appears in the bottom-right corner (default position). Click it to open the chat panel.

Install the SDK package:

npm install @agentictrust/ui

Render the inline widget anywhere in your app:

import { Widget } from "@agentictrust/ui";

export default function App() {
  return (
    <div style={{ height: 720 }}>
      <Widget
        apiUrl="https://platform.agentictrust.com/api/v1"
        apiKey="lum_pk_your_api_key"
      />
    </div>
  );
}

The component renders in embedded mode and injects styles through a shadow root — no CSS import needed.

Install the SDK package:

npm install @agentictrust/ui

Use the widget from a client component:

"use client";

import { Widget } from "@agentictrust/ui";

export default function Page() {
  return (
    <div style={{ height: 720 }}>
      <Widget
        apiUrl="https://platform.agentictrust.com/api/v1"
        apiKey={process.env.NEXT_PUBLIC_AGENTIC_TRUST_API_KEY!}
      />
    </div>
  );
}

For a floating bubble instead of an embedded panel, use initAsync with cleanup:

"use client";

import { initAsync, destroy } from "@agentictrust/ui";
import { useEffect } from "react";

export default function FloatingWidget() {
  useEffect(() => {
    initAsync({
      apiUrl: "https://platform.agentictrust.com/api/v1",
      apiKey: process.env.NEXT_PUBLIC_AGENTIC_TRUST_API_KEY!,
    });
    return () => destroy();
  }, []);

  return null;
}

Configuration options

Pass these properties to init, initAsync, or Widget:

Property	Type	Required	Description
`apiUrl`	`string`	Yes	API base URL (e.g. `https://platform.agentictrust.com/api/v1`)
`apiKey`	`string`	Yes	Public API key (`lum_pk_...`)
`user`	`UserIdentity`	No	End-user identity for HMAC verification (see Identity)
`userTokens`	`Record<string, string>`	No	Auth headers forwarded to action endpoints
`pageContext`	`PageContext`	No	Page metadata sent with messages
`getPageContext`	`() => PageContext`	No	Dynamic page context fetcher called before each message
`captureDom`	`boolean`	No	Auto-capture headings, links, buttons, and form fields from the page
`readOnly`	`boolean`	No	Hide the chat input so no new messages can be sent
`navigate`	`(path: string) => void \| Promise<void>`	No	SPA-friendly navigation function (e.g. `router.push`). See SPA navigation
`embedded`	`boolean`	No	Render inline instead of as a floating bubble (auto-set by `Widget`)

When the agent decides to navigate the user to a different page, it calls the navigate function you provide. This keeps your SPA’s router in control instead of triggering a full page reload.

"use client";

import { useRouter } from "next/navigation";
import { Widget } from "@agentictrust/ui";

export default function WidgetWithNav() {
  const router = useRouter();

  return (
    <Widget
      apiUrl="https://platform.agentictrust.com/api/v1"
      apiKey="lum_pk_your_api_key"
      navigate={(path) => router.push(path)}
    />
  );
}

The widget waits for the route change to complete before capturing the new page context and responding to the agent. Both synchronous (() => void) and async (() => Promise<void>) functions are accepted.

If you don’t pass navigate, the widget falls back to window.location.href which triggers a full page reload. The conversation state is preserved in localStorage and the agent continues automatically after the page loads.

Full example

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <h1>Welcome</h1>

  <script src="https://platform.agentictrust.com/widget.js"></script>
  <script>
    AgenticTrust.initAsync({
      apiUrl: "https://platform.agentictrust.com/api/v1",
      apiKey: "lum_pk_your_api_key",
      user: {
        id: "user-42",
        email: "user@example.com",
        name: "Jane Doe",
        hmac: "computed_hex_signature"
      },
      userTokens: {
        Authorization: "Bearer user_jwt"
      }
    });
  </script>
</body>
</html>

The widget script is cached for 1 hour with a stale-while-revalidate window of 1 day. Users always get a fast load with automatic background updates.

Getting Started

Features

Widget Integration

Install

Configuration options

SPA navigation

Full example

​Install

​Configuration options

​SPA navigation

​Full example

Install

Configuration options

SPA navigation

Full example