> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentictrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Add the Agentic Trust chat widget to your website with a script tag or the @agentictrust/ui npm package.

The Agentic Trust widget is available as a hosted script for any HTML site, an npm package ([`@agentictrust/ui`](https://www.npmjs.com/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

<Tabs>
  <Tab title="Script tag">
    Include the widget script and initialize it — no build step required.

    **1. Add the script**

    ```html theme={null}
    <script src="https://platform.agentictrust.com/widget.js"></script>
    ```

    **2. Initialize**

    <CodeGroup>
      ```html initAsync (recommended) theme={null}
      <script>
        AgenticTrust.initAsync({
          apiUrl: "https://platform.agentictrust.com/api/v1",
          apiKey: "lum_pk_your_api_key"
        });
      </script>
      ```

      ```html init (synchronous) theme={null}
      <script>
        AgenticTrust.init({
          apiUrl: "https://platform.agentictrust.com/api/v1",
          apiKey: "lum_pk_your_api_key"
        });
      </script>
      ```
    </CodeGroup>

    `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. Verify**

    Reload your page. A chat bubble appears in the bottom-right corner (default position). Click it to open the chat panel.
  </Tab>

  <Tab title="React">
    Install the SDK package:

    ```bash theme={null}
    npm install @agentictrust/ui
    ```

    Render the inline widget anywhere in your app:

    ```tsx theme={null}
    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.
  </Tab>

  <Tab title="Next.js">
    Install the SDK package:

    ```bash theme={null}
    npm install @agentictrust/ui
    ```

    Use the widget from a client component:

    ```tsx theme={null}
    "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:

    ```tsx theme={null}
    "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;
    }
    ```
  </Tab>
</Tabs>

## 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](/widget/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](#spa-navigation) |
| `embedded`       | `boolean`                                 | No       | Render inline instead of as a floating bubble (auto-set by `Widget`)                         |

## SPA navigation

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.

```tsx theme={null}
"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.

<Note>
  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.
</Note>

## Full example

```html theme={null}
<!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>
```

<Note>
  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.
</Note>