Docs / SDK / For coding agents / For coding agents

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 maps each code and HTTP error to its fix.