# Create a conversation
Source: https://docs.agentictrust.com/api-reference/chat/create-a-conversation

/openapi.json post /chat/conversations
Creates a new conversation. Optionally associate it with an end user by passing `endUserExternalId`.



# Get conversation messages
Source: https://docs.agentictrust.com/api-reference/chat/get-conversation-messages

/openapi.json get /chat/conversations/{conversationId}
Returns the full ordered message history for a conversation.



# List conversations
Source: https://docs.agentictrust.com/api-reference/chat/list-conversations

/openapi.json get /chat/conversations
Returns up to 20 conversations for a given end user, ordered by most recently updated. Only conversations with at least one message are returned.



# Send a message
Source: https://docs.agentictrust.com/api-reference/chat/send-a-message

/openapi.json post /chat/messages
Sends a message to the AI agent and returns a streaming SSE response. The request body must not exceed 1 MB.



# Submit feedback
Source: https://docs.agentictrust.com/api-reference/feedback/submit-feedback

/openapi.json post /chat/feedback
Records a positive or negative rating for a conversation, optionally targeting a specific message.



# Identify user (JWT)
Source: https://docs.agentictrust.com/api-reference/identity/identify-user-jwt

/openapi.json post /identity/identify
Verifies a JWT identity token signed with the project's HMAC secret (HS256). On success, the end user is upserted from the token claims (`sub` required; `email` and `name` optional).



# Verify user identity (HMAC)
Source: https://docs.agentictrust.com/api-reference/identity/verify-user-identity-hmac

/openapi.json post /identity/verify
Verifies an end user's identity using HMAC-SHA256. The HMAC is computed over the `userId` with the project's HMAC secret. On success, the end user is upserted.



# Get widget configuration
Source: https://docs.agentictrust.com/api-reference/widget/get-widget-configuration

/openapi.json get /widget/config
Returns the merged widget configuration for the project associated with the API key, including available workflows (skills).



# Analytics
Source: https://docs.agentictrust.com/features/analytics

Monitor conversations, collect feedback, and track how your agent is performing.

The analytics dashboard gives you visibility into every conversation your agent handles. Track resolution quality, identify gaps in your knowledge base, and collect user feedback.

## Activity feed

The **Activity** page in the dashboard shows a real-time feed of conversations. Each entry includes:

* Conversation status (active or closed)
* Message count and last message preview (up to 150 characters)
* Timestamps for creation and last update
* End user identity (if verified)

The feed polls every 2 seconds and shows up to 50 messages per poll, with a maximum monitoring duration of 5 minutes per session.

## Conversation history

Click any conversation in the activity feed to see the full message history. You can review:

* The complete exchange between the user and agent
* Which knowledge sources and actions were used
* Tool invocations and their results
* Page context captured from the widget

## Feedback collection

Users can rate agent responses directly in the widget. Feedback is captured via the `/api/v1/chat/feedback` endpoint with:

| Field       | Description                          |
| ----------- | ------------------------------------ |
| `rating`    | `POSITIVE` or `NEGATIVE`             |
| `messageId` | Optional — target a specific message |
| `comment`   | Optional — free-text explanation     |

<Tip>
  Use negative feedback to identify topics where your knowledge base needs improvement. Filter conversations by negative ratings to find common pain points.
</Tip>

## API access

You can query conversation data programmatically:

<CodeGroup>
  ```bash List conversations theme={null}
  curl "https://platform.agentictrust.com/api/v1/chat/conversations?userId=user-42" \
    -H "x-api-key: lum_pk_your_api_key"
  ```

  ```bash Get conversation messages theme={null}
  curl "https://platform.agentictrust.com/api/v1/chat/conversations/conv_abc123" \
    -H "x-api-key: lum_pk_your_api_key"
  ```

  ```bash Submit feedback theme={null}
  curl -X POST "https://platform.agentictrust.com/api/v1/chat/feedback" \
    -H "x-api-key: lum_pk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"conversationId": "conv_abc123", "rating": "POSITIVE"}'
  ```
</CodeGroup>

## Rate limits

| Endpoint         | Limit              |
| ---------------- | ------------------ |
| Chat messages    | 30 requests/minute |
| Session creation | 10 requests/minute |
| General API      | 60 requests/minute |

Rate limit headers are included in every response:

* `X-RateLimit-Limit` — maximum requests in the current window
* `X-RateLimit-Remaining` — requests remaining
* `X-RateLimit-Reset` — Unix timestamp when the window resets


# Custom Actions
Source: https://docs.agentictrust.com/features/custom-actions

Connect your APIs so the agent can take actions on behalf of users — look up orders, create tickets, update records, and more.

Custom actions let the AI agent call external APIs during a conversation. When a user asks "Where is my order?" the agent can call your order-lookup API and return the real answer.

## Action types

<Tabs>
  <Tab title="OpenAPI Import">
    Import an OpenAPI (Swagger) specification to automatically create actions for each endpoint.

    <Steps>
      <Step title="Go to Actions">
        Navigate to **Actions** in the dashboard sidebar.
      </Step>

      <Step title="Import OpenAPI spec">
        Click **Import OpenAPI** and paste your spec URL or upload the JSON/YAML file (max 2 MB, spec body max 500K characters).
      </Step>

      <Step title="Select endpoints">
        Choose which endpoints to expose to the agent. Each becomes a callable tool.
      </Step>
    </Steps>

    The agent sees each endpoint as a tool with the operation's summary as the description and the request schema as parameters.
  </Tab>

  <Tab title="Manual Configuration">
    Create actions one at a time with full control over the request.

    | Field         | Description                                  | Limit      |
    | ------------- | -------------------------------------------- | ---------- |
    | Name          | Tool name the agent sees                     | 100 chars  |
    | Description   | When to use this action                      | 500 chars  |
    | URL           | Endpoint URL                                 | 2048 chars |
    | Method        | HTTP method (GET, POST, PUT, DELETE, PATCH)  | —          |
    | Parameters    | Named parameters with types and descriptions | Max 20     |
    | Body template | JSON template with `{{param}}` placeholders  | 10K chars  |
    | Headers       | Static or dynamic headers                    | —          |
  </Tab>

  <Tab title="MCP Tools">
    Connect Model Context Protocol (MCP) servers to expose their tools to the agent.

    The agent runtime includes a built-in MCP proxy that connects to external MCP servers. Configure the server URL in the dashboard and the proxy discovers available tools automatically.
  </Tab>
</Tabs>

## User tokens

If your API requires user-specific authentication, the widget can forward custom headers to action endpoints via `userTokens`:

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

<Warning>
  User tokens are forwarded to action endpoints as-is. Only configure tokens for APIs you trust. Max 10 token keys, each value up to 4096 characters.
</Warning>

## Limits

| Resource              | Limit                  |
| --------------------- | ---------------------- |
| Actions per project   | 100                    |
| Parameters per action | 20                     |
| OpenAPI spec size     | 500K chars (2 MB file) |


# Identity Verification
Source: https://docs.agentictrust.com/features/identity

Verify end users with HMAC signatures or JWT tokens so the agent can access personalized data securely.

Identity verification lets you prove who a user is before the agent accesses sensitive data or performs privileged actions. Agentic Trust supports two verification methods: **HMAC** and **JWT**.

## HMAC verification

HMAC verification uses a shared secret to sign the user's ID on your backend. The widget sends the signature to Agentic Trust, which verifies it before granting access.

<Steps>
  <Step title="Generate an HMAC secret">
    Go to **Identity** in the dashboard sidebar and click **Generate Secret**. Copy the secret — it's only shown once.
  </Step>

  <Step title="Sign the user ID on your backend">
    Compute an HMAC-SHA256 signature of the user's external ID using the secret:

    <CodeGroup>
      ```javascript Node.js theme={null}
      import crypto from "crypto";

      const hmac = crypto
        .createHmac("sha256", "your_hmac_secret")
        .update("user-42")
        .digest("hex");
      ```

      ```python Python theme={null}
      import hmac
      import hashlib

      signature = hmac.new(
          b"your_hmac_secret",
          b"user-42",
          hashlib.sha256,
      ).hexdigest()
      ```

      ```ruby Ruby theme={null}
      require "openssl"

      signature = OpenSSL::HMAC.hexdigest(
        "SHA256",
        "your_hmac_secret",
        "user-42"
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Pass the signature to the widget">
    Include the user object when initializing the widget:

    ```html theme={null}
    <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"
        }
      });
    </script>
    ```
  </Step>
</Steps>

## JWT verification

JWT verification uses a signed token instead of a raw HMAC. This is useful when you already issue JWTs in your application.

<Steps>
  <Step title="Generate an HMAC secret">
    Same as above — the secret is used to sign and verify JWTs (HS256 algorithm).
  </Step>

  <Step title="Issue a JWT on your backend">
    Create a JWT with the user's ID as the `sub` claim. Optionally include `email` and `name`:

    <CodeGroup>
      ```javascript Node.js theme={null}
      import jwt from "jsonwebtoken";

      const token = jwt.sign(
        { sub: "user-42", email: "user@example.com", name: "Jane Doe" },
        "your_hmac_secret",
        { algorithm: "HS256", expiresIn: "1h" }
      );
      ```

      ```python Python theme={null}
      import jwt

      token = jwt.encode(
          {"sub": "user-42", "email": "user@example.com", "name": "Jane Doe"},
          "your_hmac_secret",
          algorithm="HS256",
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Pass the token to the widget">
    Use the `identify` method or set up automatic token refresh:

    ```html theme={null}
    <script>
      // One-time identification
      AgenticTrust.identify("your_jwt_token");

      // Or auto-refresh
      AgenticTrust.setIdentityTokenFetcher(async () => {
        const res = await fetch("/api/identity-token");
        if (!res.ok) return null;
        const data = await res.json();
        return data.token;
      });
    </script>
    ```
  </Step>
</Steps>

## Choosing between HMAC and JWT

|                | HMAC                                | JWT                           |
| -------------- | ----------------------------------- | ----------------------------- |
| **Best for**   | Simple integrations                 | Apps that already use JWTs    |
| **User data**  | Passed separately (`email`, `name`) | Embedded in token claims      |
| **Expiration** | No built-in expiry                  | Token has `exp` claim         |
| **Refresh**    | Not needed                          | Use `setIdentityTokenFetcher` |

<Warning>
  Never expose your HMAC secret in client-side code. Always compute signatures and sign tokens on your backend.
</Warning>


# Knowledge Base
Source: https://docs.agentictrust.com/features/knowledge-base

Upload documents and crawl websites to give your agent accurate, up-to-date answers grounded in your content.

The knowledge base powers Agentic Trust's RAG (Retrieval-Augmented Generation) pipeline. When a user asks a question, the agent searches your uploaded content for relevant passages and uses them to generate an accurate answer.

## How it works

1. You upload documents or add website URLs in the dashboard.
2. Content is chunked, embedded using OpenAI `text-embedding-3-small` (1536 dimensions), and stored in PostgreSQL with pgvector.
3. At query time, the agent retrieves the top 3 most similar chunks (similarity threshold: 0.4) and includes them as context.

## Supported file types

<AccordionGroup>
  <Accordion title="PDF" icon="file-pdf">
    Upload PDF documents up to 10 MB. Text is extracted and chunked automatically. Scanned PDFs with embedded text are supported.
  </Accordion>

  <Accordion title="Word (DOCX)" icon="file-word">
    Microsoft Word documents are parsed with full formatting support. Tables and lists are preserved as text.
  </Accordion>

  <Accordion title="Plain text (TXT)" icon="file-lines">
    Raw text files are chunked by paragraph boundaries.
  </Accordion>

  <Accordion title="Markdown (MD)" icon="file-code">
    Markdown files are parsed with heading-aware chunking so sections stay together.
  </Accordion>

  <Accordion title="CSV" icon="file-csv">
    CSV files are converted to structured text. Each row becomes a retrievable unit.
  </Accordion>
</AccordionGroup>

## Website crawling

You can also add website URLs as knowledge sources. The crawler:

* Fetches the page content and extracts readable text
* Follows internal links to crawl related pages
* Re-crawls on demand when you trigger a refresh from the dashboard

<Steps>
  <Step title="Add a website source">
    Go to **Knowledge** in the dashboard sidebar and click **Add Source**. Select **Website** and enter the URL.
  </Step>

  <Step title="Wait for ingestion">
    The crawler fetches and processes the pages. Progress is shown in the source list.
  </Step>

  <Step title="Test it">
    Open the chat widget and ask a question about the content you just added.
  </Step>
</Steps>

## Limits

| Resource            | Limit                   |
| ------------------- | ----------------------- |
| Sources per project | 20                      |
| Files per upload    | 15                      |
| Max file size       | 10 MB                   |
| Supported formats   | PDF, DOCX, TXT, MD, CSV |

<Note>
  The knowledge base uses cosine similarity search. If the agent isn't finding relevant content, try breaking large documents into smaller, topic-focused files.
</Note>


# Models
Source: https://docs.agentictrust.com/features/models

Choose from 8 AI models across 5 providers. Compare pricing and find the right fit for your use case.

Agentic Trust supports 8 AI models from 5 providers. You can select a model per project from the **Agent** page in the dashboard. The default model is **Sonnet 4.6**.

## Available models

| Model                 | Provider  | Tag         | Max Output | Description                                                      |
| --------------------- | --------- | ----------- | ---------: | ---------------------------------------------------------------- |
| Sonnet 4.6            | Anthropic | Recommended |       128K | Best balance of speed and capability for most use cases          |
| Haiku 4.5             | Anthropic | Fastest     |        64K | Fastest responses and lowest cost, ideal for high volume         |
| GPT-5.4               | OpenAI    | Powerful    |       128K | OpenAI's flagship model with 1M+ context and strong reasoning    |
| GPT-5.4 Mini          | OpenAI    | Balanced    |       128K | Fast and affordable OpenAI model for everyday tasks              |
| GPT-5.4 Nano          | OpenAI    | Budget      |       128K | Ultra-low-cost OpenAI model for simple, high-volume workloads    |
| GLM 5.1               | Z.ai      | —           |        64K | Z.ai's latest model with 200K context and competitive pricing    |
| Gemini 3.1 Flash Lite | Google    | Lightweight |        64K | Google's lightweight flash model with 1M context at minimal cost |
| MiniMax M2.7          | MiniMax   | —           |       128K | MiniMax's latest model with 200K context and very low cost       |

## Pricing

All prices are **per million tokens** (USD).

| Model                 |  Input | Cache Write | Cache Read |  Output |
| --------------------- | -----: | ----------: | ---------: | ------: |
| Sonnet 4.6            | \$3.00 |      \$3.75 |     \$0.30 | \$15.00 |
| Haiku 4.5             | \$1.00 |      \$1.25 |     \$0.10 |  \$5.00 |
| GPT-5.4               | \$2.50 |      \$3.13 |     \$0.25 | \$15.00 |
| GPT-5.4 Mini          | \$0.75 |      \$0.94 |    \$0.075 |  \$4.50 |
| GPT-5.4 Nano          | \$0.20 |      \$0.25 |     \$0.02 |  \$1.25 |
| GLM 5.1               | \$0.95 |      \$1.19 |     \$0.10 |  \$3.15 |
| Gemini 3.1 Flash Lite | \$0.25 |      \$0.31 |    \$0.025 |  \$1.50 |
| MiniMax M2.7          | \$0.30 |      \$0.38 |     \$0.03 |  \$1.20 |

## Choosing a model

<Tip>
  Start with **Sonnet 4.6** (the default). Switch to **Haiku 4.5** if you need faster responses at lower cost, or **GPT-5.4** for maximum capability.
</Tip>

| Use case                   | Recommended model                     | Why                                      |
| -------------------------- | ------------------------------------- | ---------------------------------------- |
| General customer support   | Sonnet 4.6                            | Best all-around quality and the default  |
| High-volume, simple Q\&A   | Haiku 4.5                             | Fastest responses, lowest Anthropic cost |
| Complex reasoning tasks    | GPT-5.4                               | 1M+ context window, strong reasoning     |
| Everyday tasks on a budget | GPT-5.4 Mini                          | Good quality at \$0.75/1M input          |
| Maximum cost efficiency    | GPT-5.4 Nano or Gemini 3.1 Flash Lite | Under \$0.25/1M input                    |
| Long document generation   | MiniMax M2.7 or GLM 5.1               | High max output with low cost            |

## Changing the model

Go to **Agent** in your project dashboard and select a model from the model grid. The change takes effect for new conversations immediately.

## Model policy

Admins can restrict which models are available to a project from the **Settings > Models** page. Disabled models are hidden from the model selector. At least one model must remain enabled.


# Navigation
Source: https://docs.agentictrust.com/features/navigation

Upload a routes.csv file so the agent knows your site's page structure and can direct users to the right pages.

The navigation feature gives the agent awareness of your site's page structure. When a user asks "Where can I change my billing info?" the agent can point them to the exact page instead of giving a generic answer.

## How it works

1. You generate a `routes.csv` file describing your application's pages.
2. You upload the CSV in the dashboard.
3. The agent receives the route structure as context and references specific pages when guiding users.

## Downloads

<CardGroup>
  <Card title="routes-template.csv" icon="file-csv" href="/downloads/routes-template.csv">
    Starter CSV template. Fill in your pages and upload.
  </Card>

  <Card title="AI skill (file)" icon="robot" href="/downloads/build-routes-skill.md">
    Download the skill for Cursor, Codex, or any AI editor.
  </Card>

  <Card title="Install in Cursor" icon="arrow-pointer" href="https://cursor.com/link/command?name=build-routes&text=Build+a+routes.csv+file+for+this+application+by+discovering+all+navigable+routes.%0A%0AScan+the+codebase+for+route+definitions%3A%0A-+Next.js+App+Router%3A+app%2F%2A%2A%2Fpage.tsx+directories%0A-+React+Router%3A+createBrowserRouter%2C+Route+path+configs%0A-+Vue+Router%3A+routes+arrays+in+router+configs%0A-+Angular%3A+RouterModule.forRoot%2C+Routes+arrays%0A-+Any+URL+path+patterns+in+the+codebase%0A-+If+the+app+is+running%2C+explore+navigation+in+the+browser%0A%0AOutput+CSV+with+header%3A+name%2Cpath%2Cdescription%2Cparameters%0A-+name%3A+unique+snake_case+identifier+%28e.g.+settings_billing%2C+user_detail%29%0A-+path%3A+URL+path+with+%3AparamName+for+dynamic+segments%0A-+description%3A+one-line+summary+of+what+the+page+shows+or+does%0A-+parameters%3A+semicolon-separated+paramName%3Atype+pairs%3B+empty+for+static+routes%0A%0AExample%3A%0Aname%2Cpath%2Cdescription%2Cparameters%0Adashboard%2C%2Fdashboard%2CMain+dashboard+overview%2C%0Auser_detail%2C%2Fusers%2F%3AuserId%2CIndividual+user+profile%2CuserId%3Astring%0Asettings_billing%2C%2Fsettings%2Fbilling%2CBilling+and+subscription+management%2C%0A%0AOrganization%3A+dashboard%2Fhome+pages+first%2C+feature+pages+next%2C+settings%2Fadmin+last.%0ADeduplicate%2C+remove+stale+entries%2C+validate+unique+names%2C+paths+start+with+%2F%2C+params+match+placeholders.%0AWrite+the+result+to+routes.csv+in+the+project+root.">
    One-click install as a reusable Cursor command.
  </Card>
</CardGroup>

## Adding navigation routes

<Steps>
  <Step title="Generate your routes.csv">
    Create a `routes.csv` file following the format below. You can:

    * **One-click with Cursor** — [install the build-routes command](https://cursor.com/link/command?name=build-routes\&text=Build+a+routes.csv+file+for+this+application+by+discovering+all+navigable+routes.%0A%0AScan+the+codebase+for+route+definitions%3A%0A-+Next.js+App+Router%3A+app%2F%2A%2A%2Fpage.tsx+directories%0A-+React+Router%3A+createBrowserRouter%2C+Route+path+configs%0A-+Vue+Router%3A+routes+arrays+in+router+configs%0A-+Angular%3A+RouterModule.forRoot%2C+Routes+arrays%0A-+Any+URL+path+patterns+in+the+codebase%0A-+If+the+app+is+running%2C+explore+navigation+in+the+browser%0A%0AOutput+CSV+with+header%3A+name%2Cpath%2Cdescription%2Cparameters%0A-+name%3A+unique+snake_case+identifier+%28e.g.+settings_billing%2C+user_detail%29%0A-+path%3A+URL+path+with+%3AparamName+for+dynamic+segments%0A-+description%3A+one-line+summary+of+what+the+page+shows+or+does%0A-+parameters%3A+semicolon-separated+paramName%3Atype+pairs%3B+empty+for+static+routes%0A%0AExample%3A%0Aname%2Cpath%2Cdescription%2Cparameters%0Adashboard%2C%2Fdashboard%2CMain+dashboard+overview%2C%0Auser_detail%2C%2Fusers%2F%3AuserId%2CIndividual+user+profile%2CuserId%3Astring%0Asettings_billing%2C%2Fsettings%2Fbilling%2CBilling+and+subscription+management%2C%0A%0AOrganization%3A+dashboard%2Fhome+pages+first%2C+feature+pages+next%2C+settings%2Fadmin+last.%0ADeduplicate%2C+remove+stale+entries%2C+validate+unique+names%2C+paths+start+with+%2F%2C+params+match+placeholders.%0AWrite+the+result+to+routes.csv+in+the+project+root.) and let the AI generate it from your codebase.
    * **Start from the template** — download the [routes-template.csv](/downloads/routes-template.csv) and fill in your own pages.
    * **Use the AI skill** — download the [build-routes skill](/downloads/build-routes-skill.md) for any AI coding editor.
    * **Build manually** — follow the format specification and examples below.
  </Step>

  <Step title="Upload in the dashboard">
    Navigate to **Navigation** in the dashboard sidebar and upload your `routes.csv` file.
  </Step>

  <Step title="The agent uses it automatically">
    The navigation context is included in the agent's system prompt. No additional configuration needed.
  </Step>
</Steps>

## CSV format

The `routes.csv` file uses four columns:

```csv theme={null}
name,path,description,parameters
dashboard_home,/dashboard,Main dashboard with project overview,
settings_general,/settings,Account and project settings,
settings_billing,/settings/billing,Billing and subscription management,
user_detail,/users/:userId,Individual user profile and account info,userId:string
```

| Column        | Description                                                                                                     |
| ------------- | --------------------------------------------------------------------------------------------------------------- |
| `name`        | A unique snake\_case identifier for the route (e.g. `settings_billing`, `user_detail`)                          |
| `path`        | The URL path. Use `:paramName` for dynamic segments (e.g. `/users/:userId`)                                     |
| `description` | A short plain-English summary of what the page shows or does                                                    |
| `parameters`  | Dynamic parameter definitions as `paramName:type` pairs, separated by semicolons. Leave empty for static routes |

### Formatting rules

* The first row must be the header: `name,path,description,parameters`
* Every `name` must be unique across the file
* Every `path` must start with `/`
* Dynamic segments in `path` must use `:paramName` syntax and have a matching entry in `parameters`
* Only quote fields if they contain a comma
* Group related routes together for readability

## Generating routes from your codebase

You can extract routes from common frontend frameworks:

<AccordionGroup>
  <Accordion title="Next.js (App Router)">
    Each directory under `app/` with a `page.tsx` maps to a route. Dynamic segments use `[paramName]` folders.

    ```
    app/
    ├── dashboard/page.tsx        → /dashboard
    ├── settings/page.tsx         → /settings
    ├── settings/billing/page.tsx → /settings/billing
    └── users/[userId]/page.tsx   → /users/:userId
    ```

    Convert bracket syntax to colon syntax: `[userId]` becomes `:userId`.
  </Accordion>

  <Accordion title="React Router">
    Search your router configuration for `path` properties:

    ```jsx theme={null}
    createBrowserRouter([
      { path: "/dashboard", element: <Dashboard /> },
      { path: "/users/:userId", element: <UserDetail /> },
    ]);
    ```

    Each `path` value maps directly to a row in the CSV.
  </Accordion>

  <Accordion title="Vue / Angular">
    Look for route arrays in your router config. Vue uses `path` in `routes: [...]`, Angular uses `RouterModule.forRoot(...)`. The path format is the same.
  </Accordion>

  <Accordion title="Manual discovery">
    Navigate your application and record each page's URL. Replace dynamic values (IDs, slugs) with `:paramName` placeholders. Check your sidebar, navbar, tabs, and settings pages for the full list.
  </Accordion>
</AccordionGroup>

## Examples

A small application with a dashboard, settings, and user management:

```csv theme={null}
name,path,description,parameters
dashboard,/dashboard,Main dashboard with project overview,
dashboard_analytics,/dashboard/analytics,Usage analytics and charts,
settings_general,/settings,General account settings,
settings_billing,/settings/billing,Billing and subscription management,
settings_api_keys,/settings/api-keys,API key management and rotation,
users,/users,User listing and search,
user_detail,/users/:userId,Individual user profile and account info,userId:string
user_permissions,/users/:userId/permissions,User role and permission management,userId:string
help,/help,Help center and documentation,
help_getting_started,/help/getting-started,Getting started guide for new users,
```

A larger application with nested routes and multiple parameter types:

```csv theme={null}
name,path,description,parameters
workspaces,/workspaces,Workspace listing and management,
test_cases,/td/:workspaceId/cases,Test case listing and management,workspaceId:string
test_case_detail,/td/cases/:testCaseId,Individual test case detail and steps,testCaseId:string
environments,/td/:workspaceId/environments,Environment listing and management,workspaceId:string
```

<Tip>
  Write descriptions that match how users ask about each page. "Billing and subscription management" is better than just "Billing" because it helps the agent match user intent more accurately.
</Tip>

## Auto-generate with AI

Let your AI coding agent scan your codebase and produce the `routes.csv` for you.

<Tabs>
  <Tab title="Cursor (one-click)">
    Click the link below to install `build-routes` as a reusable command in Cursor. You'll be asked to review the command before it's saved.

    <a href="https://cursor.com/link/command?name=build-routes&text=Build+a+routes.csv+file+for+this+application+by+discovering+all+navigable+routes.%0A%0AScan+the+codebase+for+route+definitions%3A%0A-+Next.js+App+Router%3A+app%2F%2A%2A%2Fpage.tsx+directories%0A-+React+Router%3A+createBrowserRouter%2C+Route+path+configs%0A-+Vue+Router%3A+routes+arrays+in+router+configs%0A-+Angular%3A+RouterModule.forRoot%2C+Routes+arrays%0A-+Any+URL+path+patterns+in+the+codebase%0A-+If+the+app+is+running%2C+explore+navigation+in+the+browser%0A%0AOutput+CSV+with+header%3A+name%2Cpath%2Cdescription%2Cparameters%0A-+name%3A+unique+snake_case+identifier+%28e.g.+settings_billing%2C+user_detail%29%0A-+path%3A+URL+path+with+%3AparamName+for+dynamic+segments%0A-+description%3A+one-line+summary+of+what+the+page+shows+or+does%0A-+parameters%3A+semicolon-separated+paramName%3Atype+pairs%3B+empty+for+static+routes%0A%0AExample%3A%0Aname%2Cpath%2Cdescription%2Cparameters%0Adashboard%2C%2Fdashboard%2CMain+dashboard+overview%2C%0Auser_detail%2C%2Fusers%2F%3AuserId%2CIndividual+user+profile%2CuserId%3Astring%0Asettings_billing%2C%2Fsettings%2Fbilling%2CBilling+and+subscription+management%2C%0A%0AOrganization%3A+dashboard%2Fhome+pages+first%2C+feature+pages+next%2C+settings%2Fadmin+last.%0ADeduplicate%2C+remove+stale+entries%2C+validate+unique+names%2C+paths+start+with+%2F%2C+params+match+placeholders.%0AWrite+the+result+to+routes.csv+in+the+project+root.">**Install build-routes command in Cursor**</a>

    Once installed, run the command from Cursor's command palette anytime you need to regenerate routes.
  </Tab>

  <Tab title="Cursor (quick prompt)">
    Open Cursor chat and click this link to pre-fill a one-shot prompt:

    <a href="https://cursor.com/link/prompt?text=Build+a+routes.csv+for+my+app.+Scan+the+codebase+for+all+route+definitions+%28Next.js+pages%2C+React+Router%2C+Vue%2FAngular+routers%29.+Output+CSV%3A+name+%28snake_case%29%2C+path+%28with+%3Aparam+placeholders%29%2C+description+%28one-line%29%2C+parameters+%28paramName%3Atype%29.+Group+by+dashboard%2C+features%2C+settings.+Write+to+routes.csv.">**Open build-routes prompt in Cursor**</a>
  </Tab>

  <Tab title="Any AI editor">
    1. Download the [build-routes skill](/downloads/build-routes-skill.md)
    2. Save it to your project:
       * **Cursor**: `.cursor/skills/build-routes/SKILL.md`
       * **Codex**: `.codex/skills/build-routes/SKILL.md`
       * **Generic**: `.agents/skills/build-routes/SKILL.md`
    3. Ask your AI agent: **"Build a routes.csv for my app"**
  </Tab>
</Tabs>

The agent scans your source code for route definitions (Next.js pages, React Router configs, Vue/Angular routers), explores the live app if it's running, and produces a properly formatted CSV ready to upload.

## When to use navigation

Navigation is most useful when:

* Your product has many pages and users frequently ask "where do I find X?"
* You want the agent to link directly to relevant pages in its answers
* Your site structure changes and you want the agent to stay current

<Note>
  Navigation routes are processed and stored per project. Re-upload your `routes.csv` whenever your site structure changes.
</Note>


# Workflows
Source: https://docs.agentictrust.com/features/workflows

Define specialized agent behaviors for common scenarios like refunds, onboarding, or troubleshooting.

Workflows let you create structured, step-by-step behaviors that the agent follows when handling specific types of requests. Instead of relying solely on the system prompt, workflows give the agent a detailed playbook for each scenario.

## How workflows work

1. You create a workflow in the dashboard with a name, description, and detailed content.
2. The agent sees available workflows as "skills" it can activate.
3. When a user's request matches a workflow, the agent uses the `generate_workflow` tool to follow the defined steps.

## Creating a workflow

<Steps>
  <Step title="Navigate to Workflows">
    Go to **Workflows** in the dashboard sidebar.
  </Step>

  <Step title="Create a new workflow">
    Click **New Workflow** and fill in:

    * **Name** — a short label the agent uses to identify the workflow (max 64 characters)
    * **Description** — when the agent should activate this workflow (max 1024 characters)
    * **Content** — the full step-by-step instructions (max 50K characters)
  </Step>

  <Step title="Test it">
    Open the chat widget and ask a question that should trigger the workflow. The agent will follow the defined steps.
  </Step>
</Steps>

## Example workflows

<AccordionGroup>
  <Accordion title="Refund request" icon="receipt">
    Guide the agent through collecting order details, verifying eligibility, and processing the refund via a custom action.
  </Accordion>

  <Accordion title="Onboarding" icon="user-plus">
    Walk new users through account setup, feature discovery, and initial configuration step by step.
  </Accordion>

  <Accordion title="Troubleshooting" icon="wrench">
    Define a diagnostic flow: collect symptoms, check known issues, escalate if unresolved.
  </Accordion>
</AccordionGroup>

## AI-assisted workflow generation

The dashboard includes an AI assistant that helps you draft workflow content. Describe what you want the workflow to do and the assistant generates the step-by-step instructions for you.

## Limits

| Resource              | Limit             |
| --------------------- | ----------------- |
| Workflows per project | 20                |
| Name length           | 64 characters     |
| Description length    | 1024 characters   |
| Content length        | 50,000 characters |


# Introduction
Source: https://docs.agentictrust.com/introduction

Agentic Trust is an AI-powered customer support platform that lets you deploy intelligent chat agents on your website in minutes.

Agentic Trust gives your customers instant, accurate answers by combining a knowledge base, custom actions, workflows, and identity verification into a single embeddable widget.

<CardGroup>
  <Card title="Knowledge Base" icon="book" href="/features/knowledge-base">
    Upload PDFs, docs, CSVs, or crawl your website. The RAG pipeline retrieves relevant context so the agent answers from your content.
  </Card>

  <Card title="Custom Actions" icon="bolt" href="/features/custom-actions">
    Connect any API with OpenAPI specs, manual configuration, or MCP tools. The agent can take actions on behalf of users.
  </Card>

  <Card title="Workflows" icon="route" href="/features/workflows">
    Define specialized behaviors for common scenarios like refunds, onboarding, or troubleshooting.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/features/identity">
    Verify end users with HMAC signatures or JWT tokens so the agent can access personalized data securely.
  </Card>

  <Card title="Widget Integration" icon="code" href="/widget/installation">
    Install [`@agentictrust/ui`](https://www.npmjs.com/package/@agentictrust/ui) for React/Next.js, or drop a script tag into your site. Configure appearance, register client-side tools, and control the widget programmatically.
  </Card>

  <Card title="Analytics" icon="chart-line" href="/features/analytics">
    Monitor conversations, collect feedback, and track resolution rates from the dashboard.
  </Card>
</CardGroup>

## How it works

1. **Configure your agent** in the dashboard — set a system prompt, choose a model, and upload knowledge sources.
2. **Embed the widget** on your site with the [`@agentictrust/ui`](https://www.npmjs.com/package/@agentictrust/ui) React SDK or a single script tag.
3. **Users ask questions** and the agent streams answers using your knowledge base, actions, and workflows.
4. **Monitor and improve** through the activity feed, feedback ratings, and conversation history.

## Architecture overview

Agentic Trust runs as a Next.js application backed by PostgreSQL with pgvector. Chat requests are routed to a Cloudflare Worker that hosts a Durable Object per conversation, with MCP tool servers for knowledge retrieval, custom actions, and workflow execution.

| Component       | Technology                                                   |
| --------------- | ------------------------------------------------------------ |
| Dashboard & API | Next.js (App Router), React, Tailwind CSS                    |
| Database        | PostgreSQL + pgvector (Drizzle ORM)                          |
| Auth            | WorkOS AuthKit (dashboard), API keys (widget)                |
| AI Models       | Claude Sonnet 4.6, Haiku 4.5, GPT-5.2, Gemini, and more      |
| Embeddings      | OpenAI `text-embedding-3-small` (1536 dimensions)            |
| Agent Runtime   | Cloudflare Worker + Durable Object (one DO per conversation) |

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get your first agent running in under 5 minutes.
  </Card>

  <Card title="API Reference" icon="square-terminal" href="/api-reference">
    Explore the full runtime API with interactive examples.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.agentictrust.com/quickstart

Get your first Agentic Trust agent running in under 5 minutes.

This guide walks you through embedding the chat widget on your site and sending your first message.

## Prerequisites

* An Agentic Trust account with a project created in the dashboard
* Your **API key** (`lum_pk_...`) from the project settings page

## Embed the widget

<Steps>
  <Step title="Add the script tag">
    Include the widget script in your HTML:

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

  <Step title="Initialize the widget">
    Call `initAsync` with your project credentials:

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

      ```html With user identity theme={null}
      <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: "hex_sha256_signature"
          }
        });
      </script>
      ```
    </CodeGroup>

    The widget bubble appears in the bottom-right corner of your page.
  </Step>

  <Step title="Test it out">
    Click the widget bubble and send a message. If you've added knowledge sources in the dashboard, the agent will answer from your content.
  </Step>
</Steps>

## Send a message via the API

You can also interact with the agent programmatically.

<Steps>
  <Step title="Create a conversation">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://platform.agentictrust.com/api/v1/chat/conversations" \
        -H "x-api-key: lum_pk_your_api_key" \
        -H "Content-Type: application/json" \
        -d '{"endUserExternalId": "user-42"}'
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch("https://platform.agentictrust.com/api/v1/chat/conversations", {
        method: "POST",
        headers: {
          "x-api-key": "lum_pk_your_api_key",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ endUserExternalId: "user-42" }),
      });
      const { conversationId } = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.post(
          "https://platform.agentictrust.com/api/v1/chat/conversations",
          headers={"x-api-key": "lum_pk_your_api_key"},
          json={"endUserExternalId": "user-42"},
      )
      conversation_id = res.json()["conversationId"]
      ```
    </CodeGroup>

    Save the `conversationId` from the response.
  </Step>

  <Step title="Stream a response">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -N -X POST "https://platform.agentictrust.com/api/v1/chat/messages" \
        -H "x-api-key: lum_pk_your_api_key" \
        -H "Content-Type: application/json" \
        -d '{
          "conversationId": "conv_abc123",
          "messages": [{"role": "user", "content": "Hello, how can I reset my password?"}]
        }'
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch("https://platform.agentictrust.com/api/v1/chat/messages", {
        method: "POST",
        headers: {
          "x-api-key": "lum_pk_your_api_key",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          conversationId: "conv_abc123",
          messages: [{ role: "user", content: "Hello, how can I reset my password?" }],
        }),
      });

      const reader = res.body.getReader();
      const decoder = new TextDecoder();
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        process.stdout.write(decoder.decode(value));
      }
      ```

      ```python Python theme={null}
      import requests

      res = requests.post(
          "https://platform.agentictrust.com/api/v1/chat/messages",
          headers={"x-api-key": "lum_pk_your_api_key"},
          json={
              "conversationId": "conv_abc123",
              "messages": [{"role": "user", "content": "Hello, how can I reset my password?"}],
          },
          stream=True,
      )

      for chunk in res.iter_content(decode_unicode=True):
          print(chunk, end="")
      ```
    </CodeGroup>

    The response streams back as Server-Sent Events.
  </Step>
</Steps>

## What's next

<CardGroup>
  <Card title="Knowledge Base" icon="book" href="/features/knowledge-base">
    Upload documents and crawl websites so the agent answers from your content.
  </Card>

  <Card title="Custom Actions" icon="bolt" href="/features/custom-actions">
    Let the agent call your APIs to take actions on behalf of users.
  </Card>

  <Card title="Widget Configuration" icon="palette" href="/widget/configuration">
    Customize the widget appearance, position, and color scheme.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/features/identity">
    Secure your agent with HMAC or JWT identity verification.
  </Card>
</CardGroup>


# Client-Side Tools
Source: https://docs.agentictrust.com/widget/client-tools

Register browser-side tools, subscribe to tool results, and control page context from JavaScript.

The widget exposes a JavaScript API for advanced integrations. You can register tools the agent can invoke in the browser, subscribe to server-side tool results, customize how tools render in the chat, and update page context.

## Page context

Tell the agent about the current page so it can give context-aware answers:

```javascript theme={null}
AgenticTrust.setContext({
  title: document.title,
  url: location.href,
  description: "Checkout page — user is reviewing their cart",
});
```

The context is sent with the next message. The widget also captures DOM context automatically (headings, buttons, links, form fields) within configured limits.

<Note>
  Automatic DOM capture limits: 80 links, 30 headings, 30 buttons, 20 form fields, 8000 characters of text content.
</Note>

## Registering client-side tools

Register JavaScript functions that the agent can invoke during a conversation. The agent calls these via the built-in `invoke_client_tool` bridge:

```javascript theme={null}
AgenticTrust.registerTools({
  open_help_center: async ({ path }) => {
    window.location.href = `/help/${String(path ?? "")}`;
    return { success: true };
  },

  get_cart_items: async () => {
    const items = JSON.parse(localStorage.getItem("cart") ?? "[]");
    return { items, count: items.length };
  },

  apply_discount: async ({ code }) => {
    const res = await fetch(`/api/discounts/${code}`);
    if (!res.ok) return { error: "Invalid code" };
    const data = await res.json();
    return { discount: data.percentage };
  },
});
```

Each tool receives a single argument object with the parameters the agent provides. Return a JSON-serializable result.

## Subscribing to tool results

Listen for server-side tool invocations (knowledge retrieval, custom actions, workflows):

```javascript theme={null}
const unsubscribe = AgenticTrust.onToolResult((event) => {
  console.log("Tool:", event.toolName);
  console.log("Result:", event.result);

  if (event.toolName === "navigate" && event.result.url) {
    window.location.href = event.result.url;
  }
});

// Later, to stop listening:
unsubscribe();
```

## Custom tool renderers

Override how specific tools appear in the chat UI:

```javascript theme={null}
AgenticTrust.registerToolRenderers({
  navigate: (invocation) => ({
    text: `Navigating to ${String(invocation.args.url ?? "target page")}...`,
  }),

  lookup_order: (invocation) => ({
    text: `Looking up order ${String(invocation.args.orderId ?? "")}...`,
  }),
});
```

The renderer receives the tool invocation and returns an object with a `text` property displayed as a status message in the chat.

## API summary

| Method                             | Description                                    |
| ---------------------------------- | ---------------------------------------------- |
| `setContext(ctx)`                  | Update page context for the next message       |
| `registerTools(tools)`             | Register browser-side tools the agent can call |
| `onToolResult(callback)`           | Subscribe to server-side tool results          |
| `registerToolRenderers(renderers)` | Customize tool display in the chat UI          |


# Configuration
Source: https://docs.agentictrust.com/widget/configuration

Customize the widget's appearance, position, and behavior from the dashboard.

The widget's visual appearance is configured in the **Design** section of your project dashboard. Changes take effect immediately for new page loads (the widget config is fetched on `initAsync`).

## Appearance settings

| Setting          | Default        | Options                                           |
| ---------------- | -------------- | ------------------------------------------------- |
| Position         | `bottom-right` | `bottom-right`, `bottom-left`                     |
| Show branding    | `true`         | `true`, `false`                                   |
| Primary color    | —              | Any CSS color                                     |
| Background color | —              | Any CSS color                                     |
| Text color       | —              | Any CSS color                                     |
| Input background | —              | Any CSS color                                     |
| Input text color | —              | Any CSS color                                     |
| Navigation color | —              | Any CSS color (shades derived for bg, icon, text) |
| Font family      | —              | Any CSS font-family                               |
| FAB icon         | —              | URL to a custom bubble icon                       |
| FAB text         | —              | Text label on the bubble                          |

Panel width (**520px**) and border radius (**16px**) are fixed in the widget and are not configurable via the dashboard or API. The color scheme is fixed to **dark**.

To revert a color to its default, clear the field in the dashboard editor and save. Sending `null` via the API removes the override.

## Position

Control where the chat bubble appears on the page:

* **bottom-right** — default, suits most layouts
* **bottom-left** — use when the bottom-right conflicts with other UI elements

## Branding

When `showBranding` is enabled, the widget displays a small "Powered by Agentic Trust" badge. Disable it for a white-label experience.

## Widget config API

The widget fetches its configuration from `GET /api/v1/widget/config` on initialization. The response includes all design settings plus available workflows (skills):

```json theme={null}
{
  "showBranding": true,
  "position": "bottom-right",
  "primaryColor": "#F97316",
  "availableSkills": [
    {
      "id": "wf_abc123",
      "name": "Refund Request",
      "description": "Process a refund for an order"
    }
  ]
}
```

<Tip>
  Use `initAsync` instead of `init` to ensure the widget picks up your dashboard configuration. With `init`, the widget renders with hardcoded defaults.
</Tip>


# Widget Identity
Source: https://docs.agentictrust.com/widget/identity

Pass user identity to the widget using HMAC signatures or JWT tokens.

When you verify a user's identity, the agent can access personalized data and perform privileged actions. The widget supports two methods: passing identity at initialization and programmatic JWT identification.

## Identity at initialization

Pass the `user` object when initializing the widget. The widget calls the HMAC verification endpoint automatically:

```html theme={null}
<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: "hex_sha256_signature"
    }
  });
</script>
```

<Warning>
  The `hmac` value must be computed on your backend. See [Identity Verification](/features/identity) for server-side signing examples.
</Warning>

## JWT identification

Use `identify()` to verify the user with a JWT token after the widget has initialized:

```javascript theme={null}
AgenticTrust.identify("eyJhbGciOiJIUzI1NiIs...");
```

The token must be signed with your project's HMAC secret using HS256. Required claim: `sub` (user ID). Optional claims: `email`, `name`.

## Auto-refresh tokens

For long-lived sessions, set up automatic token refresh so the identity stays valid:

```javascript theme={null}
AgenticTrust.setIdentityTokenFetcher(async () => {
  const res = await fetch("/api/agentic-trust/identity-token");
  if (!res.ok) return null;
  const data = await res.json();
  return data.token;
});
```

The widget calls your fetcher when the current token expires and re-identifies the user automatically.

## Backend token endpoint

Here's an example backend endpoint that issues identity tokens:

<CodeGroup>
  ```javascript Express.js theme={null}
  import jwt from "jsonwebtoken";

  app.get("/api/agentic-trust/identity-token", (req, res) => {
    if (!req.user) return res.status(401).json({ error: "Not authenticated" });

    const token = jwt.sign(
      { sub: req.user.id, email: req.user.email, name: req.user.name },
      process.env.AGENTIC_TRUST_HMAC_SECRET,
      { algorithm: "HS256", expiresIn: "1h" }
    );

    res.json({ token });
  });
  ```

  ```python Flask theme={null}
  import jwt
  from flask import request, jsonify

  @app.route("/api/agentic-trust/identity-token")
  def identity_token():
      if not current_user.is_authenticated:
          return jsonify(error="Not authenticated"), 401

      token = jwt.encode(
          {"sub": current_user.id, "email": current_user.email, "name": current_user.name},
          os.environ["AGENTIC_TRUST_HMAC_SECRET"],
          algorithm="HS256",
      )

      return jsonify(token=token)
  ```
</CodeGroup>

## Verification flow

```
Your Backend                Widget                  Agentic Trust API
    │                         │                           │
    │  sign JWT / compute HMAC│                           │
    │◄────────────────────────│                           │
    │  return token/signature │                           │
    │────────────────────────►│                           │
    │                         │  POST /identity/verify    │
    │                         │  or /identity/identify    │
    │                         │──────────────────────────►│
    │                         │  { verified: true }       │
    │                         │◄──────────────────────────│
```


# Installation
Source: https://docs.agentictrust.com/widget/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>