Mindset AI

Docs / Get started / Concepts

Two ways to put an agent in your product

The drop-in element versus the headless client — same backend handshake, same agent, different amount of interface you write.

You can embed a Mindset AI agent into your own application in one of two ways. Both use the same backend handshake and the same agent. What differs is how much of the interface you write.

The two paths

The drop-in element. One script tag and one HTML tag, and a working chat interface appears on your page. We render it, we style it, we handle the streaming and the state. You write no interface code.

The core functionality is available without our UI — same conversation functionality with no user interface at all. You get events as the agent thinks and replies, and commands to drive it. Every pixel is yours.

Good to know: The visible <mindset-agent> tag supports exactly the same set of methods, properties and events that the UI-less variant does.

Drop-in element Headless client
What you write Two tags and a session function Your entire interface
What we render A full chat panel Nothing
How you load it Script tag ES module import by URL
Time to first message Minutes Hours to days, depending on your design
Styling CSS custom properties we expose However you like
Good for Support widgets, in-app assistants, anything where our chat UI is fine Products where the agent has to look like it was always part of your app

Which to pick

Start with the drop-in element. It's faster to get running, and it's the same underlying contract, so moving to the headless client later isn't a rewrite of your backend.

Choose the headless client when the conversation needs to live inside an interface you already have, when the agent's output drives something other than a chat transcript, or when your design system won't tolerate a component you don't control.

You can also mix them. The element is a thin shell over the same commands the headless client exposes, with no private channel to the runtime, so there's nothing the element can do that you can't. If you do want to mix them, make sure you include our full SDK build that includes our UI, even if you don't want to render it on the page.

How trust works

The important thing to understand before you write any code: your organization's API key never reaches a browser.

Your backend                    Mindset AI
------------                    ----------
Holds the org API key   ---->   Creates a session
(server to server)      <----   Returns an opaque credential

      |
      | hands the credential to the browser
      v

Your page
---------
Holds the session credential  ---->  Runs the agent
(one agent, one user)         <----  Streams the reply

Your backend makes one server-to-server call with your organization's API key and gets back a credential. That credential is scoped to one agent, one user, one organization and one Environment. It's the only thing that goes to the browser.

The API key is admin-grade. The session credential is not: it can run one agent and nothing else, and it's refused on every management surface regardless of who the user is. Even an org admin's session credential can only run the one agent it was made for.

The SDK keeps the session alive by itself. You don't write refresh logic, and there's no renewal endpoint for you to call.

What runs where

The agent runtime runs in the browser, not on our servers. Your page loads it as part of the SDK bundle, and it orchestrates the conversation from there, calling back to us for inference and tool execution.

That's what makes page tools possible: the agent can call a function you define, running in your page, with your application's context.

Your knowledge, your agent configuration and your conversation history stay on the Mindset AI platform.

What you don't have to build

Session renewal. The SDK handles it. When it can't, it asks your backend for a new session, which is the same call you already wrote.

Streaming. Replies arrive token by token, and both paths hand you that stream.

Conversation resume. The element gives you a conversation ID after a user's first completed turn. Store it against that user, hand it back on their next visit, and they pick up where they left off.

Style isolation. The drop-in element renders in a shadow root with its own compiled stylesheet, so your CSS and ours can't interfere with each other.

What isn't here yet

Worth knowing before you plan around something that doesn't exist.

No conversation management API. You can resume a specific conversation by handing back its ID, but there's no way to list a user's conversations, rename one, delete one, or switch between them programmatically. Resume is configuration rather than a command.

No self-hosted SDK bundle. The SDK is served from your Mindset AI host and loaded by script tag or URL import. There's nothing to install, and you always get the current build.

No published rate limits. We don't publish limits for the embed surface today.

The SDK is additive-only, meaning new events and new fields appear but existing ones don't change shape or disappear. Build consumers that ignore anything they don't recognize and you'll be fine across updates.

Where to go next

  • "Put an agent on your page" is the ten-minute quickstart. Start here.
  • "Create a session for your users" covers the backend call in full.
  • "The mindset-agent element" is the reference for the drop-in path.
  • "The UI-less SDK" is the reference for building your own interface.