# For coding agents

> Point a coding agent at these docs in Markdown, and give it the facts it needs to embed a Mindset agent correctly.

Use this page to give a coding agent (Claude Code, Cursor, Copilot and the like) what it needs to embed a Mindset agent in your app. It covers where to read these docs as Markdown and the facts an agent most often gets wrong.

## Read the docs as Markdown

| Address | What it holds |
|---|---|
| Any page URL plus `.md` | That page as Markdown. For example `/docs/sdk/put-an-agent-on-your-page.md` |
| `/llms.txt` | An index of every page, each with a one-line summary and a link to its Markdown version |
| `/llms-full.txt` | The full text of every page in one file |
| `/.well-known/agent-skills/index.json` | The published skills, each with a name, description and link |
| `/skills` | The same skills, for a person to browse |

For an embedding task, give your agent these four pages first:

- `/docs/sdk/put-an-agent-on-your-page.md`
- `/docs/sdk/create-a-session-for-your-users.md`
- `/docs/sdk/the-mindset-agent-element.md`
- `/docs/sdk/the-ui-less-client.md`

## Facts to give your coding agent

Paste this into your agent's instructions, or point it at this page.

**Backend.**

- Create a session with `POST https://<host>/api/v1/orgs/<orgSlug>/envs/<envSlug>/agent-sessions`, sending the org API key in the `x-api-key` header. Server side only. The route has no CORS headers.
- The body is strict JSON: `user` with exactly one of `email` or `externalId`, `agent` (handle or ID), `createUserIfNeeded: true`, and optionally `attribution` (string values). Any other field is a 400.
- Return the response body to the browser unchanged, with `cache-control: no-store`. Don't extract `session` from it.
- Never put the org API key in frontend code, a response, or a log.

**Frontend, drop-in.**

- Load `<script src="https://<host>/sdk/mindset-agent.js"></script>` once. It registers `<mindset-agent>`.
- Write `<mindset-agent agent="<handle>"></mindset-agent>` and call `element.configure({ getSession })`.
- `getSession` is a function that fetches your backend endpoint and returns `await r.json()`. Not a string, not a `Response`.
- Supported `configure()` fields: `getSession`, `conversationId`, `conversationList`, `pageTools`, `situationalAwareness`, `passthroughParams`, `agent`.
- Methods: `configure`, `send`, `stop`, `setPageTools`, `setSituationalAwareness`, `setPassthroughParams`.
- Events: `mindset:runtime-event`, `mindset:error` (branch on `detail.code`), `mindset:conversation`.
- React 19 and Vue 3 use the element directly. There is no wrapper package and no npm package.

**Frontend, UI-less.**

- `import { createAgentConversation } from "https://<host>/sdk/mindset-agent-uiless.js"`.
- `createAgentConversation({ agent, getSession, conversationId? })` calls `getSession` immediately.
- Commands: `send`, `sendMessage`, `widgetAction`, `stop`, `retry`, `reset`, `setPageTools`, `setSituationalAwareness`, `setPassthroughParams`, `listConversations`, `switchConversation`. State: `transcript()`, `messages()`, `conversationId`, `enabledFeatures()`. Subscribe with `on()`, which returns an unsubscribe function.
- Render from `transcript()` and events, never from `messages()`.

**Both.**

- Switch on `event.type` and ignore unknown types. The vocabulary only grows.
- Store the `conversationId` from the latest `conversation_id` event (`mindset:conversation` on the element) per user, and pass it back next visit.
- Page tool handlers get model-chosen arguments. Validate them and check permissions in the handler or your backend.
- Don't use members that aren't listed here, even if your editor offers them. They are internal and can change without notice.

## When something doesn't work

Have your agent read the browser console. The element logs every `mindset:error` there with its code and a message naming the setting to change. The [troubleshooting table](https://docs4.mindset.ai/docs/sdk/put-an-agent-on-your-page#troubleshooting) maps each code and HTTP error to its fix.