Skip to main content
<mindset-agent> is the customer-facing surface of the Mindset AI SDK. Drop it in your HTML, give it an agent UID, and an agent appears. The element handles auth, streaming, state, and (unless you opt out) rendering its own chat UI. 
<mindset-agent agent-uid="agt-abc123"></mindset-agent>
You configure the element with HTML attributes for one-time setup, listen for events to react to what the agent does, and call methods on it to drive turns. This page covers the attributes and the registration lifecycle. See the methods reference and events reference for the full method and event surface.

​
Two modes: chat UI vs headless

The element has one optional toggle that changes everything: the headless attribute.

​
Default (chat UI rendered)

Without headless, the element renders Mindset AI’s built-in chat UI inside a shadow DOM. Your users see a chat panel; you don’t write any UI code. 
<mindset-agent agent-uid="agt-abc123"></mindset-agent>
This is the right choice when:
  • You want a working chat experience in minutes
  • Mindset AI’s UI matches your needs (configurable theme, customizable widgets, branded buttons)
  • You don’t have strong design constraints

​
Headless (you render the UI)

With headless, the element runs the agent and dispatches DOM events but does not render any UI. You build the chat (or whatever interface you want) using events and methods. 
<mindset-agent agent-uid="agt-abc123" headless></mindset-agent>
This is the right choice when:
  • You have an existing UI design and want the agent to drive it
  • You need a non-chat surface, like voice, slash commands, or an embedded recommendation panel
  • You’re integrating into a framework (React, Vue, Svelte) and want full control
The runtime, state machine, auth flow, and DOM events are identical in both modes. The only difference is whether the element renders its own chat UI.
Icebreakers fire in headless mode too. If your agent is configured with an icebreaker (a turn that fires automatically when the agent starts), it runs in headless mode just like it does with the built-in chat UI. You’ll see mindset:agent-busy → mindset:text-delta → mindset:complete → mindset:agent-idle before your first sendMessage runs. Use the sendWhenIdle pattern to handle this safely.

​
Attributes

You set attributes once when the element is added to the DOM. The element reads them on first render. After that, use the corresponding JS methods to update values dynamically.

​
Required

AttributeTypeDescription
agent-uidstring (UID)The agent to load. Each agent in the Agent Management Studio has a unique UID.
Your app’s UID is not a per-element attribute. Pass it once via mindset.init({ appUid }). It’s a page-level concern and applies to every <mindset-agent> element on the page.

​
Mode

AttributeTypeDescription
headlessboolean (presence wins)When present, the element runs the agent without rendering UI. See Two modes.

​
Configuration (alternative to JS methods)

Each of these attributes mirrors a JS method on the element. The attribute path is convenient when your initial setup is static and known at render time. Use the JS method when you need to update the value later.
AttributeTypeEquivalent method
passthrough-paramsJSON object as stringagent.setPassthroughParams(params)
situational-awarenessJSON object as stringagent.setSituationalAwareness(sa)
initial-questionstringAuto-sends a first message when the agent loads
thread-uidstring (thread UID)Resumes an existing thread on mount. Works in both modes. No icebreaker fires when this is set, because the agent loads the existing thread’s history instead.
themeJSON ThemeConfig as stringPer-agent theme override
show-thread-list"true" or "false"Show or hide the thread list panel in the chat UI. Default: true. Ignored in headless mode.
Most of these accept both kebab-case and camelCase forms (passthrough-params and passthroughParams work the same). Kebab-case is the recommended form because it’s the HTML standard. 
<mindset-agent
  agent-uid="agt-abc123"
  situational-awareness='{"currentPage":"/products","userPlan":"enterprise"}'
  initial-question="What's new this week?"
></mindset-agent>

​
Properties

Properties are read-only fields you access on the element instance after it’s registered.
PropertyTypeDescription
agent.threadUidstring | nullThe active thread UID. null if the element isn’t bound to a runtime yet, or if the current thread is local-only (just created via newThread(), no persisted user-message turn yet). See thread-uid persistence semantics.
const agent = document.querySelector('mindset-agent');
console.log('Active thread:', agent.threadUid);
The thread UID is also available via the mindset:thread-changed event when it changes.

​
Methods

The element has methods for driving turns, configuring per-agent state, and managing threads. All documented in the methods reference. Quick summary:
  • agent.sendMessage(text, options?) sends a user message
  • agent.setPageTools(tools), setSituationalAwareness(sa), setPassthroughParams(params) configure per-agent state
  • agent.newThread(), switchThread(uid), deleteThread(uid), renameThread(uid, title), listThreads(options?) manage threads
  • agent.isAgentBusy() checks turn state

​
Registration lifecycle

The element follows the standard custom-element lifecycle. Knowing the order helps when you’re debugging “why isn’t my listener firing” or coordinating timing across init and DOM mount.

​
When the SDK script loads

The class is registered globally: 
customElements.get('mindset-agent'); // returns the constructor (MindsetAgentElement)
You can verify the SDK has loaded by checking this. Until it returns a value, the element is unknown to the browser.

​
When the element is added to the DOM

The browser fires connectedCallback, which the element uses to:
  1. Set data-mindset-element-registered="true" and data-mindset-headless="true" (or "false") on the DOM node
  2. Dispatch mindset:agent-registered with event.detail = { headless: boolean }
At this point the element exists and you can attach event listeners, but the runtime isn’t bound yet. Wait for mindset:agent-idle before calling methods like setPageTools or sendMessage. See § When the element is ready to call.

​
When mindset.init() completes and binds the element

The init pipeline finds the element, attaches a runtime instance, and sets data-instance-id="<id>" on the DOM node. The agent begins initializing and will fire mindset:agent-initializing followed by mindset:agent-idle once ready. Methods are safe to call from mindset:agent-idle onward.

​
When the element is removed from the DOM

The browser fires disconnectedCallback. The element detaches its event bridges and cleans up. State setters called after this point are no-ops.

​
Registration signals you can rely on

SignalWhereWhen set
customElements.get('mindset-agent') returns the constructorglobalAfter the SDK bundle script loads
data-mindset-element-registered="true"DOM attributeAfter connectedCallback
data-mindset-headless="true" or "false"DOM attributeAfter connectedCallback
mindset:agent-registered eventBubbles from the elementOn connectedCallback
data-instance-id="<id>"DOM attributeAfter mindset.init() binds the element
mindset:agent-idle eventBubbles from the elementAfter init completes successfully
If you need to know that a specific element is ready to take messages, listen for mindset:agent-idle on it. If the agent has an icebreaker configured, the first mindset:agent-idle (init done) is followed immediately by an icebreaker turn, and the agent is fully ready for customer-driven sendMessage calls after the second mindset:agent-idle. Use the sendWhenIdle pattern to handle both cases without needing to know which configuration applies.

​
Dynamic mounting (frameworks)

The SDK uses a MutationObserver to detect <mindset-agent> elements added to the DOM after mindset.init() has run. This means React, Vue, Svelte, and other frameworks that mount the element in a component lifecycle work without extra wiring: 
function ChatPanel({ agentUid }) {
  return <mindset-agent agent-uid={agentUid} headless />;
}
The observer picks up the element when React mounts it, runs the same registration sequence as a static element, and dispatches mindset:agent-registered. Unmounting fires disconnectedCallback and cleans up the runtime binding. See the Examples page (Headless: React tab) for the full pattern, including refs, useEffect cleanup, and event subscription.

​
What’s not on the element

These are SDK-level concerns, not per-agent. Set them via mindset.init(), not on individual elements:
  • appUid: your app’s identity, shared by every <mindset-agent> element on the page
  • extendedSituationalAwareness: lifts the SA character limit from 10,000 to 20,000 for every agent on the page
  • fetchAuthentication callback
  • Auth state helpers (onAuthStateChanged, signInWithGoogle, etc.)
See the SDK init reference for the full SDK-level API.