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>
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
| Field | Type | Required | Description |
|---|
appUid | string | Yes | Your 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. |
extendedSituationalAwareness | boolean | No | Lifts the situational-awareness character limit from 10,000 to 20,000 across the page. Default: false. |
theme | ThemeConfig | No | Page-level theme override. Per-element theme attributes override this. |
initialQuestion | string | No | Default 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;
},
});
- 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.
| Function | Returns | Description |
|---|
window.mindset.onAuthStateChanged(callback) | unsubscribe function | Fires 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();
fetchAuthentication to mint tokens server-side, you don’t need these helpers.
Page-level utilities
| Function | Description |
|---|
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
| Concern | Set on | Example |
|---|
| App identity | init config | appUid |
| User identity | init config | fetchAuthentication |
| Page-wide defaults | init config | extendedSituationalAwareness, theme, initialQuestion |
| Auth state listening | window.mindset.* | onAuthStateChanged |
| Per-agent identity | element attribute | agent-uid |
| Per-agent runtime mode | element attribute | headless |
| Per-agent context | element method | setSituationalAwareness, setPassthroughParams, setPageTools |
| Per-agent turns | element method | sendMessage |
| Per-agent threads | element method | newThread, switchThread, etc. |
window.mindset.
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}`);
});
