Docs / SDK / Start / How embedding works

How embedding works

Pick the drop-in element or the UI-less client, and see how a session keeps your org API key out of the browser.

After this page you can choose how to put a Mindset agent into your web app, and you know which part of the integration runs on your server and which runs in the browser.

This section is for a web developer adding an agent that already exists. Building the agent happens in AMS. Start at What Mindset is if you need that side.

The example on every SDK page is the same: a billing web app that puts an agent with the handle billing-help in front of its signed-in users.

What this is

There are two ways to embed an agent. Both use the same backend call, the same session and the same agent. They differ in how much interface you write.

	Drop-in element	UI-less client
What you write	One script tag, one HTML tag and a session function	Your whole chat interface
What Mindset renders	A complete chat panel	Nothing
How you load it	`<script src="https://YOUR-MINDSET-HOST/sdk/mindset-agent.js">`	`import` from `https://YOUR-MINDSET-HOST/sdk/mindset-agent-uiless.js`
Styling	CSS custom properties on the element	Entirely yours
Good for	Support widgets and in-app assistants where the Mindset chat UI fits	An agent that has to look native to your app, or whose output drives something other than a transcript

Start with the drop-in element. It is quicker to get running, and switching to the UI-less client later changes only your frontend. Your backend call stays the same.

The element is a thin shell over the UI-less client. Every element method maps to a UI-less command of the same name, and the element has no private channel to the agent runtime.

How trust works

Your organization's API key never reaches a browser. The flow has two halves.

Your backend calls Mindset once, server to server, with the org API key. Mindset creates a session for one of your users and returns a JSON body holding an opaque credential.
Your backend hands that JSON body to the browser. The SDK runs the agent with it.

The credential is scoped to one agent, one user, one org and one environment. Mindset accepts it only on the surfaces that run the agent (inference, tool calls and run events). It is refused on every management surface, whatever role the user holds in your org.

The API key is admin-grade. Keep it on your server and out of logs.

What runs where

Where	What runs there
Your server	The one call that creates a session
The browser	The SDK and the agent's turn loop, which calls Mindset for model inference and tool calls. Page tools (functions you define in your page) also run here
Mindset	The agent's configuration, its connections and knowledge, model calls, server-side tools, and the stored conversation history

Because the turn loop runs in the page, the agent can call functions in your page with your app's context. See page tools.

What the SDK does for you

Session renewal. The SDK renews its own access token while the page is open. When it can no longer renew, for example after a page reload, it calls your session function again and your backend creates a new session.

Streaming. Replies arrive in pieces as the model writes them, on both paths.

Conversation continuity. The SDK tells you a conversation ID after the user's first completed turn. Store it for that user and hand it back next visit to resume.

Conversation list. On request, the element shows the user their earlier conversations with this agent. The UI-less client gives you the same list as data.

Style isolation. The element renders in a shadow root with its own stylesheet, so your CSS and the element's CSS don't reach each other.

What isn't possible

No npm package. Both bundles are served from your Mindset host. There is nothing to install, and the bundle always matches the platform version it is served from. You can't pin an older version.
No renaming or deleting conversations from the SDK. You can list a user's conversations with one agent and switch between them.
No ::part() styling on the element. Theming is by CSS custom properties only.
No image attachments on the published SDK yet.

How the SDK changes

The SDK is additive only. New events, new fields and new error codes can appear. Existing ones keep their names and shapes. Write code that handles what it knows and ignores anything it doesn't recognize.

Before you start

An agent in AMS with a configuration version in force, and Embedded in your own product ticked under its availability. See Publish and share an agent.
An org API key for the environment you are embedding from. An org admin creates one in Settings → API keys.
The agent's Embed tab in AMS. It shows your host, org slug, environment slug and the agent's handle, filled in for you.

Where to go next

Put an agent on your page gets a working agent on a page.
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 client is the reference for building your own interface.
Events reference lists every event.