Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mindset.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Mindset AI SDK is initialized once per page. After the bundle loads from your <script> tag, you call window.mindset.init() with your app UID and an authentication callback. The init function attaches runtime instances to every <mindset-agent> element on the page and watches for new ones added later. Per-agent setup happens on the element itself, not here. This page covers the page-level API: the things you do once.

​
window.mindset.init(config)

Initialize the SDK. Call once after the bundle loads. Signature: 
window.mindset.init(config: InitConfig): Promise<void>
Returns: A promise that resolves once the SDK has set up shared resources. The agents themselves initialize in parallel. Listen for mindset:agent-idle on each element to know it’s ready. Note that an agent configured with an icebreaker will fire that turn immediately after the first idle event. The sendWhenIdle pattern handles this so you don’t need to track which configuration applies.

​
InitConfig

FieldTypeRequiredDescription
appUidstringYesYour app’s UID. Available in the Agent Management Studio.
fetchAuthentication() => Promise<string>Yes (for authenticated agents)Async callback the SDK calls to obtain a user token. See Authentication below.
extendedSituationalAwarenessbooleanNoLifts the situational-awareness character limit from 10,000 to 20,000 across the page. Default: false.
themeThemeConfigNoPage-level theme override. Per-element theme attributes override this.
initialQuestionstringNoDefault first question used by all agents on the page. Per-element initial-question overrides.
window.mindset.init({
  appUid: 'your-app-uid',
  fetchAuthentication: async () => {
    const r = await fetch('/api/mindset-token', { credentials: 'include' });
    const { authToken } = await r.json();
    return authToken;
  },
});

​
When to call init

You can call init before or after <mindset-agent> elements are in the DOM. Both orders work:
  • If you init first and then add elements (common when you mount agents from a JS framework like React or Vue), the SDK’s MutationObserver picks up elements as they’re added.
  • If you add elements first and then init (common with static HTML), the SDK finds existing elements and binds them.
Either way, the page-level config and per-element attributes apply at bind time. Element methods (setPageTools, setSituationalAwareness, sendMessage, thread CRUD, etc.) become callable after mindset.init() completes and the element fires mindset:agent-idle. See § When the element is ready to call.

​
Authentication

The SDK delegates auth to your fetchAuthentication callback. The callback returns a token your app’s backend mints from sdkusersapi. The SDK exchanges that token for the credentials the runtime needs. 
window.mindset.init({
  appUid: 'your-app-uid',
  fetchAuthentication: async () => {
    // Call your own backend, which calls sdkusersapi
    const r = await fetch('/api/mindset-token', { credentials: 'include' });
    const { authToken } = await r.json();
    return authToken;
  },
});
The callback runs:
  • Once when the SDK first needs a token
  • Again whenever the token expires and needs refreshing
You write the callback as if it always fetches fresh. The SDK handles caching and refresh timing internally.
Token endpoint setup. Setting up the backend endpoint that mints SDK tokens (calling sdkusersapi, configuring API keys, mapping users to Mindset AI identities) is a one-time piece of integration work covered in the existing Mindset AI auth docs.See the SDK 3 Authentication guide for the end-to-end flow, and the SDK Users API reference for the parameter-level detail.

​
Anonymous agents

If your agent is configured to allow anonymous access in the Agent Management Studio, you can omit fetchAuthentication. The agent will run without identifying the user. Useful for public-facing demos and unauthenticated marketing pages. For authenticated agents, the callback is required. Without it, the agent fires mindset:agent-error with code: 'agent_loading_failed' (or 'model_loading_failed') instead of reaching mindset:agent-idle. Listen for mindset:agent-error during integration testing so silent auth misconfigurations are caught early.

​
Auth state helpers

The SDK exposes Firebase-backed sign-in helpers for apps that use Mindset AI’s hosted authentication. These are page-level: you call them on window.mindset, not on a specific agent.
FunctionReturnsDescription
window.mindset.onAuthStateChanged(callback)unsubscribe functionFires whenever the user’s auth state changes. Useful for showing or hiding agents based on sign-in.
window.mindset.signInWithGoogle()Promise<UserCredential>Opens the Google sign-in flow.
window.mindset.signInWithMicrosoft()Promise<UserCredential>Opens the Microsoft sign-in flow.
window.mindset.signOut()Promise<void>Signs the user out.
const unsubscribe = window.mindset.onAuthStateChanged((user) => {
  if (user) {
    showAgentPanel();
  } else {
    hideAgentPanel();
  }
});

// Later
unsubscribe();
If your app handles its own auth and uses fetchAuthentication to mint tokens server-side, you don’t need these helpers.

​
Page-level utilities

FunctionDescription
window.mindset.listWidgetTemplates()Returns the catalog of widget templates available to the agents on this page. Useful when you’re building a UI that renders tool widgets and need to know what shapes to expect.

​
What lives where

ConcernSet onExample
App identityinit configappUid
User identityinit configfetchAuthentication
Page-wide defaultsinit configextendedSituationalAwareness, theme, initialQuestion
Auth state listeningwindow.mindset.*onAuthStateChanged
Per-agent identityelement attributeagent-uid
Per-agent runtime modeelement attributeheadless
Per-agent contextelement methodsetSituationalAwareness, setPassthroughParams, setPageTools
Per-agent turnselement methodsendMessage
Per-agent threadselement methodnewThread, switchThread, etc.
The boundary: anything that varies across agents lives on the element. Anything page-wide lives on window.mindset.

​
Loading the bundle

Reference the SDK from your HTML with a single <script> tag: 
<script src="MINDSET-SERVER-URL/mindset-sdk3-headless.umd.js"></script>
The bundle is a UMD build that auto-registers <mindset-agent> as a custom element on load. No npm install, no bundler integration required.
Two bundle variants. Both mindset-sdk3.umd.js and mindset-sdk3-headless.umd.js ship the same custom-element class. Use whichever URL fits your setup. The headless variant is shipped at a stable URL specifically for integrations that don’t need the chat UI; future builds may strip the chat-UI code from this variant for a smaller download, with no change to the URL.

​
Error handling

init rejects if:
  • appUid is missing or invalid
  • The bundle hasn’t finished loading (race condition, so use a defer script or call init from DOMContentLoaded)
Errors during agent loading surface on the affected element as mindset:agent-error with a code (e.g. model_loading_failed, agent_loading_failed) and a human-readable message. Listen on the element if you want to handle these: 
agent.addEventListener('mindset:agent-error', (e) => {
  console.error(`Agent error [${e.detail.code}]: ${e.detail.message}`);
});