> ## 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. # Examples > Four complete starter integrations. Pick the tab that matches your stack: the built-in chat UI, or headless mode with vanilla HTML, React, or Angular. Four complete starter integrations. The Built-in chat UI tab is the fastest path to a working agent. The three headless tabs show how to render your own UI on top of the `` element. This is the minimum integration. The element renders Mindset AI's built-in chat UI inside a shadow DOM. Your users see a chat panel; you write no UI code. ### Complete page ```html theme={null} Mindset AI agent

Support agent

Ask anything about your account, orders, or our products.

``` Replace the agent and app UIDs with yours, set up the token endpoint, and you have a working chat panel. ### What you get * Chat input and message history * Thread switcher (the user can start, switch, rename, and delete threads) * Streaming responses with typing indicator * Tool widgets rendered automatically (cards, carousels, custom UIs) * Quick reply chips and follow-up question buttons * Citation display when the agent uses retrieval * Theme that matches the page's color scheme (configurable) ### Sizing the element `` is `display: block` by default. Size it like any other block element: ```css theme={null} mindset-agent { display: block; height: 600px; width: 100%; border: 1px solid #ddd; border-radius: 8px; } ``` Common patterns: * For full-page chat, use `height: 100vh; width: 100%`. * For a sidebar, use `height: 100%; width: 360px`. * For an embedded panel, use a fixed height like the example above. The chat UI is responsive within the element. It works at sizes from \~320px wide up to full screen. ### Reacting to events Even with the built-in UI, you can hook into events to integrate the agent with the rest of your page. ```js theme={null} const agent = document.querySelector('mindset-agent'); // Sync the active thread to the URL agent.addEventListener('mindset:thread-changed', (e) => { if (e.detail.threadUid) { history.replaceState({}, '', `?thread=${e.detail.threadUid}`); } }); // Track turn completions in your analytics agent.addEventListener('mindset:complete', (e) => { analytics.track('agent_turn_complete', { threadId: e.detail.threadId, responseLength: e.detail.response.length, }); }); // Show your own loading state outside the chat panel agent.addEventListener('mindset:agent-busy', () => updateStatusIndicator('thinking')); agent.addEventListener('mindset:agent-idle', () => updateStatusIndicator('ready')); ``` ### Driving the agent from outside You can call methods on the element from anywhere on your page. Useful for: Quick-action buttons that send a pre-written message: ```html theme={null} ``` Deep-linking to a specific thread: ```js theme={null} const params = new URLSearchParams(location.search); const threadUid = params.get('thread'); document.querySelector('mindset-agent').addEventListener('mindset:agent-idle', async function once() { if (threadUid) { await this.switchThread(threadUid); } this.removeEventListener('mindset:agent-idle', once); }, { once: false }); ``` Programmatic priming. Silently prime the agent with context when the user does something on the page: ```js theme={null} document.querySelector('.cart-button').addEventListener('click', () => { const agent = document.querySelector('mindset-agent'); agent.sendMessage('the user just opened the cart panel', { silent: true }); }); ``` The agent receives the message and can respond, but no user-side bubble appears in the chat. ### Adding page tools Page tools let the agent call functions on your page during a turn. Configure them with `agent.setPageTools()`: ```js theme={null} const agent = document.querySelector('mindset-agent'); agent.setPageTools([ { name: 'lookup_order', description: 'Look up the current user\'s order by ID', parameters: { type: 'object', properties: { orderId: { type: 'string', description: 'The order ID' }, }, required: ['orderId'], }, handler: async ({ orderId }) => { const r = await fetch(`/api/orders/${orderId}`); return await r.json(); }, }, ]); ``` Call `setPageTools` once the element has fired `mindset:agent-idle`. See [When the element is ready to call](./methods.mdx#when-the-element-is-ready-to-call). ### Configuration via attributes For static setup that's known at render time, you can pass values as attributes on the element instead of calling JS methods. See the [`` reference](./mindset-agent-element.mdx#configuration-alternative-to-js-methods) for the full list. ```html theme={null} ``` Attributes are read once at render time. Use the JS method if you need to update values dynamically. ### Switching to headless later If you outgrow the built-in UI and want to render your own, add the `headless` attribute and start listening for events: ```html theme={null} ``` The runtime, state machine, auth flow, and DOM events stay the same. The only thing that changes is whether the element renders its own UI. Switch to the **Headless: vanilla HTML**, **Headless: React**, or **Headless: Angular** tab above for what that looks like end-to-end. This example builds a complete chat interface in plain HTML and JavaScript. The `` element runs the agent and dispatches DOM events; you handle rendering. No framework, no build step. ### What this example covers * Streaming text rendering as it arrives * Sending messages and managing busy state * Rendering tool widgets when the agent calls tools * Switching threads and showing thread history * Quick reply chips and follow-up question buttons ### Complete page ```html theme={null} Custom agent UI
``` ### How it works The element runs the agent. You write the rest. Three event handlers do most of the work: 1. `mindset:agent-busy` starts a new agent message bubble in the UI 2. `mindset:text-delta` appends streaming text to the current bubble 3. `mindset:agent-idle` re-enables the send button. The turn is done. Everything else (tool widgets, quick replies, thread changes) is layered on top with additional event listeners. The `sendWhenIdle` helper covers a subtle case: if your agent is configured with an icebreaker (a turn that fires automatically as the agent settles after init), the agent goes idle once after init completes, then immediately busy again while the icebreaker streams, then idle a second time when the icebreaker finishes. A user clicking "Send" during that first window would otherwise hit a busy throw. `sendWhenIdle` re-checks busy state on each `mindset:agent-idle`, so it queues automatically until the agent is actually free. ### Common adjustments **Show a typing indicator.** Replace the empty agent message with a "..." while waiting for the first text delta: ```js theme={null} agent.addEventListener('mindset:agent-busy', () => { currentReplyText = ''; currentReplyEl = appendMessage('agent', '…'); // visible while streaming starts }); agent.addEventListener('mindset:text-delta', (e) => { currentReplyText += e.detail.content; if (currentReplyEl) currentReplyEl.textContent = currentReplyText; // overwrite the … }); ``` **Render markdown in agent replies.** Pipe `currentReplyText` through your favorite markdown library before setting it on the element. Re-render on every delta: ```js theme={null} import { marked } from 'https://cdn.jsdelivr.net/npm/marked/lib/marked.esm.js'; agent.addEventListener('mindset:text-delta', (e) => { currentReplyText += e.detail.content; if (currentReplyEl) currentReplyEl.innerHTML = marked.parse(currentReplyText); }); ``` **Handle interrupts.** Some turns pause for input. The agent calls a UI-interrupt tool (e.g. `present_choices`) and waits. Listen for `mindset:interrupt`, render UI based on `e.detail.args`, then drive the next turn with `agent.sendMessage()` once the user selects: ```js theme={null} agent.addEventListener('mindset:interrupt', (e) => { // e.detail.interruptType identifies the tool that paused the turn. // e.detail.args carries the data your UI needs to render. const userSelection = await promptUserForChoice(e.detail.args); agent.sendMessage(userSelection); }); ``` A dedicated programmatic-resume API on the element is on the roadmap. For now, treat interrupts as turn-ending and drive the next turn with `sendMessage()`. **Persist the active thread in the URL.** Sync `agent.threadUid` to the URL so reloads land on the same thread. Because uids only surface after a thread persists server-side, the URL won't get a value until the user's first message. That's the correct behavior, since a local-only thread can't be reloaded anyway. ```js theme={null} agent.addEventListener('mindset:thread-changed', (e) => { if (e.detail.threadUid) { history.replaceState({}, '', `?thread=${e.detail.threadUid}`); } else { // threadUid went null (between threads or after newThread() reset). history.replaceState({}, '', location.pathname); } }); // On page load, after the agent reaches idle: agent.addEventListener('mindset:agent-idle', async function once() { const threadUid = new URLSearchParams(location.search).get('thread'); if (threadUid) { try { await agent.switchThread(threadUid); } catch (err) { // The uid in the URL no longer exists (deleted, expired, or stale). // Clear the URL and continue with a fresh thread. console.warn('Stored thread no longer exists, starting fresh:', err.message); history.replaceState({}, '', location.pathname); } } agent.removeEventListener('mindset:agent-idle', once); }, { once: false }); ``` `` is a custom element, which means it works directly as a JSX tag with no wrapper component. This example shows the patterns React developers want: refs, `useEffect` for subscription, cleanup on unmount, and TypeScript types for the events. ### Initialization Call `mindset.init()` once at app startup. Don't put it inside a component's render. Call it once in your entry file or a top-level effect: ```ts theme={null} // src/lib/mindset-init.ts declare global { interface Window { mindset: { init(config: { appUid: string; fetchAuthentication: () => Promise; }): Promise; }; } } let initialized = false; export function initializeMindset() { if (initialized) return; initialized = true; window.mindset.init({ appUid: import.meta.env.VITE_MINDSET_APP_UID, fetchAuthentication: async () => { const r = await fetch('/api/mindset-token', { credentials: 'include' }); const { authToken } = await r.json(); return authToken; }, }); } ``` Call `initializeMindset()` in your app's entry point (e.g. `main.tsx`): ```tsx theme={null} import { initializeMindset } from './lib/mindset-init'; initializeMindset(); createRoot(document.getElementById('root')!).render(); ``` Make sure the SDK script is loaded in your `index.html` before the app boots: ```html theme={null} ``` ### TypeScript types for the element and events There are no shipped TypeScript declarations yet (planned). Declare the types you need locally: ```ts theme={null} // src/types/mindset.d.ts declare namespace JSX { interface IntrinsicElements { 'mindset-agent': React.DetailedHTMLProps< React.HTMLAttributes & { 'agent-uid': string; headless?: boolean | ''; 'initial-question'?: string; 'thread-uid'?: string; 'situational-awareness'?: string; 'passthrough-params'?: string; 'theme'?: string; 'show-thread-list'?: 'true' | 'false'; }, HTMLElement >; } } interface MindsetAgentElement extends HTMLElement { setPageTools(tools: PageToolDefinition[]): void; setSituationalAwareness(sa: Record): void; setPassthroughParams(params: Record): void; sendMessage(text: string, options?: { silent?: boolean }): void; isAgentBusy(): boolean; newThread(): Promise; switchThread(threadUid: string): Promise; deleteThread(threadUid: string): Promise; renameThread(threadUid: string, title: string): Promise; listThreads(options?: { pageSize?: number; pageToken?: string }): Promise<{ threads: Array<{ uid: string; title: string; createdAt: string; updatedAt: string; messageCount: number; }>; nextPageToken: string | null; hasMore: boolean; }>; readonly threadUid: string | null; } // Event detail shapes. See events reference for the full list. interface MindsetEventMap { 'mindset:agent-registered': CustomEvent<{ headless: boolean }>; 'mindset:agent-initializing': CustomEvent<{}>; 'mindset:agent-idle': CustomEvent<{}>; 'mindset:agent-busy': CustomEvent<{}>; 'mindset:agent-error': CustomEvent<{ code: string; message: string }>; 'mindset:thread-changed': CustomEvent<{ threadUid: string | null; previous: string | null }>; 'mindset:text-delta': CustomEvent<{ content: string }>; 'mindset:tool-start': CustomEvent<{ toolName: string; toolCallId: string; runId: string; silent: boolean; args?: Record; }>; 'mindset:tool-end': CustomEvent<{ toolName: string; toolCallId: string; runId: string; durationMs: number; silent: boolean; widget?: unknown; canvas?: unknown; llmToolCallId?: string; output?: string; }>; 'mindset:complete': CustomEvent<{ response: string; threadId: string }>; // …add more as you use them } interface PageToolDefinition { name: string; description: string; parameters: Record; handler: (args: any) => Promise; } ``` ### A reusable hook A small custom hook handles the common pattern: get a typed ref, subscribe to events, clean up on unmount. ```tsx theme={null} // src/hooks/useMindsetAgent.ts import { useEffect, useRef } from 'react'; export function useMindsetAgent() { const ref = useRef(null); function on( type: K, handler: (e: MindsetEventMap[K]) => void, ) { useEffect(() => { const el = ref.current; if (!el) return; el.addEventListener(type as string, handler as EventListener); return () => el.removeEventListener(type as string, handler as EventListener); }, [handler]); } return { ref, on }; } ``` ### A chat component Putting it together: ```tsx theme={null} // src/components/AgentChat.tsx import { useState, useCallback } from 'react'; import { useMindsetAgent } from '../hooks/useMindsetAgent'; interface Message { role: 'user' | 'agent'; text: string; } interface Props { agentUid: string; } export function AgentChat({ agentUid }: Props) { const { ref, on } = useMindsetAgent(); const [messages, setMessages] = useState([]); const [busy, setBusy] = useState(false); const [input, setInput] = useState(''); const onBusy = useCallback(() => { setBusy(true); setMessages((prev) => [...prev, { role: 'agent', text: '' }]); }, []); const onIdle = useCallback(() => { setBusy(false); }, []); const onDelta = useCallback((e: MindsetEventMap['mindset:text-delta']) => { setMessages((prev) => { const next = [...prev]; const last = next[next.length - 1]; if (last && last.role === 'agent') { next[next.length - 1] = { ...last, text: last.text + e.detail.content }; } return next; }); }, []); const onComplete = useCallback((e: MindsetEventMap['mindset:complete']) => { console.log('Turn done in thread', e.detail.threadId); }, []); on('mindset:agent-busy', onBusy); on('mindset:agent-idle', onIdle); on('mindset:text-delta', onDelta); on('mindset:complete', onComplete); // sendWhenIdle handles the case where the agent is still busy with its // icebreaker turn (an automatic first turn some agents are configured to // fire on startup). If the agent is idle, it sends straight away; if it's // busy, it waits for the next mindset:agent-idle and recurses. Safe to call // at any time. function sendWhenIdle(agent: MindsetAgentElement, text: string) { if (!agent.isAgentBusy()) { agent.sendMessage(text); } else { agent.addEventListener( 'mindset:agent-idle', () => sendWhenIdle(agent, text), { once: true }, ); } } function send(e: React.FormEvent) { e.preventDefault(); const text = input.trim(); if (!text || !ref.current) return; setMessages((prev) => [...prev, { role: 'user', text }]); sendWhenIdle(ref.current, text); setInput(''); } return ( <>
{messages.map((m, i) => (
{m.text}
))}
`, }) export class AgentChatComponent implements AfterViewInit { // agentUid is a required input: readonly agentUid = input.required(); @ViewChild('agent') private agentRef!: ElementRef; protected readonly messages = signal([]); protected readonly busy = signal(false); protected readonly input = signal(''); private readonly zone = inject(NgZone); private readonly destroyRef = inject(DestroyRef); ngAfterViewInit(): void { const el = this.agentRef.nativeElement; onAgentEvent(el, 'mindset:agent-busy', () => { this.busy.set(true); this.messages.update((prev) => [...prev, { role: 'agent', text: '' }]); }, this.zone, this.destroyRef); onAgentEvent(el, 'mindset:agent-idle', () => { this.busy.set(false); }, this.zone, this.destroyRef); onAgentEvent(el, 'mindset:text-delta', (e) => { this.messages.update((prev) => { const next = [...prev]; const last = next[next.length - 1]; if (last && last.role === 'agent') { next[next.length - 1] = { ...last, text: last.text + e.detail.content }; } return next; }); }, this.zone, this.destroyRef); onAgentEvent(el, 'mindset:complete', (e) => { console.log('Turn done in thread', e.detail.threadId); }, this.zone, this.destroyRef); } send(e: Event): void { e.preventDefault(); const text = this.input().trim(); const el = this.agentRef?.nativeElement; if (!text || !el) return; this.messages.update((prev) => [...prev, { role: 'user', text }]); this.sendWhenIdle(el, text); this.input.set(''); } // sendWhenIdle handles the case where the agent is still busy with its // icebreaker turn (an automatic first turn some agents are configured to // fire on startup). If the agent is idle, it sends straight away; if it's // busy, it waits for the next mindset:agent-idle and recurses. Safe to call // at any time. private sendWhenIdle(el: MindsetAgentElement, text: string): void { if (!el.isAgentBusy()) { el.sendMessage(text); } else { el.addEventListener( 'mindset:agent-idle', () => this.sendWhenIdle(el, text), { once: true }, ); } } } ``` ### How it works The Angular-specific pieces, and why each one matters: * `CUSTOM_ELEMENTS_SCHEMA` is required. Without it the template compiler throws `NG8001: 'mindset-agent' is not a known element`. With it, Angular passes the tag and its attributes straight to the DOM. * You can't bind `mindset:*` events in the template. Angular reads the colon in `(mindset:text-delta)` as a `target:event` pair (the same syntax as `(window:resize)`), so the binding silently targets a non-existent `mindset` global. Subscribe with `addEventListener` via `@ViewChild` instead. That's what `onAgentEvent` does. Plain DOM events without a colon would bind fine, but every Mindset AI event uses the colon. * Re-enter the Angular zone for change detection. Events come from the element, not from Angular. `zone.run()` (or a signal write under zoneless) makes sure the view updates when a `text-delta` lands. * `@ViewChild` resolves in `ngAfterViewInit`, not the constructor. The element doesn't exist until the view renders, so wire subscriptions there. `DestroyRef.onDestroy` removes them when the component is torn down, with no manual `OnDestroy` boilerplate. * Attributes go through `[attr.agent-uid]`. Custom elements read configuration from attributes, not Angular `@Input` properties. Use attribute binding (or a static `agent-uid="…"`) so the value lands in the DOM where the element reads it. `headless` is a static boolean attribute. * `sendMessage` and signal writes are sync, so call them directly from the submit handler and event callbacks. Thread CRUD is async (`newThread`, `switchThread`, and the rest), so handle the returned Promises like any other API call. * `sendWhenIdle` covers the icebreaker race. If your agent is configured with an icebreaker (a turn that fires automatically as the agent settles after init), the lifecycle is `agent-idle` (init done), then `agent-busy` (icebreaker streaming), then `agent-idle` (icebreaker done). A user clicking Send during that first window would otherwise hit a busy throw. The recursive `sendWhenIdle` re-checks busy state on each idle event, so it queues until the agent is actually free. ### Configuring page tools Set page tools after the view initializes, once you have the element ref: ```ts theme={null} ngAfterViewInit(): void { const el = this.agentRef.nativeElement; el.setPageTools([ { name: 'lookup_order', description: "Look up the current user's order by ID", parameters: { type: 'object', properties: { orderId: { type: 'string' } }, required: ['orderId'], }, handler: async ({ orderId }: { orderId: string }) => { const r = await fetch(`/api/orders/${orderId}`); return await r.json(); }, }, ]); // …event subscriptions } ``` If `ngAfterViewInit` runs before `mindset.init()` has completed (or before the SDK script has loaded), `setPageTools` won't exist on the element yet. Gate the call on a `mindset:agent-idle` listener. See [When the element is ready to call](./methods.mdx#when-the-element-is-ready-to-call) for the pattern. ### Updating situational awareness when state changes Push page state to the agent so it can personalize responses without the user repeating themselves. With signals, an `effect` runs the update whenever the source state changes: ```ts theme={null} import { effect, inject } from '@angular/core'; import { AppStateService } from './app-state.service'; private readonly appState = inject(AppStateService); constructor() { // appState exposes signals: currentPage(), userPlan(), cartItemCount() effect(() => { this.agentRef?.nativeElement.setSituationalAwareness({ currentPage: this.appState.currentPage(), userPlan: this.appState.userPlan(), cartItems: String(this.appState.cartItemCount()), }); }); } ``` If your app state lives in RxJS observables instead, subscribe and call `setSituationalAwareness` in the `next` handler, and use `takeUntilDestroyed()` for cleanup. The agent reads the latest values on its next turn either way. ## Related Every method on the element with signatures and behaviors. Every event the element fires, with payload shapes. The end-to-end setup, from token endpoint to working agent. How your application talks to the agent.