# 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](https://docs4.mindset.ai/docs/ams/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.

1. 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.
2. 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](https://docs4.mindset.ai/docs/ams/glossary). 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](https://docs4.mindset.ai/docs/sdk/the-ui-less-client#give-the-agent-context-and-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](https://docs4.mindset.ai/docs/ams/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](https://docs4.mindset.ai/docs/sdk/put-an-agent-on-your-page) gets a working agent on a page.
- [Create a session for your users](https://docs4.mindset.ai/docs/sdk/create-a-session-for-your-users) covers the backend call in full.
- [The mindset-agent element](https://docs4.mindset.ai/docs/sdk/the-mindset-agent-element) is the reference for the drop-in path.
- [The UI-less client](https://docs4.mindset.ai/docs/sdk/the-ui-less-client) is the reference for building your own interface.
- [Events reference](https://docs4.mindset.ai/docs/sdk/events-reference) lists every event.