The UI-less client

Load it

The client is an ES module served from your Mindset host. There is nothing to install. Import it from a module script or a dynamic import().

import { createAgentConversation } from "https://YOUR-MINDSET-HOST/sdk/mindset-agent-uiless.js";

The module also exports isSdkEvent, SDK_EVENT_TYPES, and version and commit for the build you loaded.

Create a conversation

const chat = createAgentConversation({
  agent: "billing-help",
  getSession: async () => {
    const r = await fetch("/api/session"); // your backend endpoint
    if (!r.ok) throw new Error("Could not start a session");
    return r.json();
  },
});

createAgentConversation calls getSession straight away, not on the first message. Each call creates a real session on your backend, so create the conversation when the user can actually use it, for example when they open the chat panel.

The SDK reads the session, renews it while the page is open, and calls getSession again when it can't renew. You write no refresh logic. The session carries your org, environment and Mindset host, so there's nothing else to configure.

If getSession returns something the SDK can't use, you get a session_error event straight away. If getSession throws (your backend was briefly unreachable), there's no event, and the SDK tries again the next time it needs a session.

Drive the conversation

Turns run one at a time. Sending a new turn while one is running cancels the running one.

The promise from send, sendMessage, widgetAction and retry rejects when the turn fails or is stopped. Most interfaces render from events and only catch the rejection:

chat.send("Why was I charged twice?").catch(() => {
  // The run_error event already told the listener what happened.
});

A stopped turn ends with a run_error event carrying aborted: true. Show it as "stopped", not as an error.

Listen

let reply = "";

const unsubscribe = chat.on((event) => {
  switch (event.type) {
    case "text_delta":
      reply += event.content;
      renderReply(reply);
      break;
    case "complete":
      reply = "";
      break;
    case "run_error":
      showNotice(event.aborted ? "Stopped" : event.message);
      reply = "";
      break;
    case "conversation_id":
      saveConversationId(event.conversationId);
      break;
    default:
      break; // ignore anything you don't recognize
  }
});

renderReply, showNotice and saveConversationId stand for your own code.

on() returns a function that unsubscribes. A listener added after construction still receives conversation_id, history_settled and session_error if they already fired.

Two kinds of event arrive here: the agent runtime's events and the SDK's own events about the conversation. isSdkEvent(event) tells them apart. Both are in the events reference. Keep a default branch, because new event types can appear.

Resume a conversation

The round trip is the same as on the element.

1. After the user's first completed turn, a conversation_id event arrives. Store event.conversationId against that user in your backend.
2. On their next visit, pass it as conversationId to createAgentConversation.
3. Wait for history_settled, draw event.messages as the earlier transcript, then open your input box.

history_settled always fires once per conversation: with the restored messages, with an empty list, or with an empty list after a failed or stalled read (it gives up after 15 seconds). So you can safely keep your input closed until it arrives. Set your own shorter limit for how long you make the user wait.

If the ID you supplied can't be used, the SDK starts a fresh conversation and sends conversation_id again before any turn, with replacedConversationId and replacedBecause: "discarded". Storing whatever arrived last keeps you correct.

Show earlier conversations

const { conversations, nextCursor } = await chat.listConversations({ limit: 20 });

for (const c of conversations) {
  addPickerRow(c.conversationId, c.title ?? "Untitled", c.updatedAt);
}

async function onPick(conversationId) {
  await chat.switchConversation(conversationId);
}

addPickerRow and onPick stand for your own picker code.

The list never includes another user's conversations or another agent's. Store the ID from the conversation_id event after a switch, or the user's next visit opens the conversation they switched away from.

Read state

transcript() re-reads every widget in the conversation on each call. Call it when state changes and keep the result, rather than calling it on every render.

messages() and transcript() are different lists. Rendering from messages() shows users silent turns and raw tool traffic they were never meant to see.

Give the agent context and tools

Three commands connect your app to the agent. Each replaces its whole set, so pass the full picture each time. Passing a shorter set is how you remove an entry. Each is read fresh on every turn.

Page tools

Each tool is { name, description, jsonSchema, execute }. The model reads description and jsonSchema to decide when to call it. execute runs in your page with the arguments the model chose and returns a string (or a promise of one), which goes back to the agent as the tool's result.

chat.setPageTools([
  {
    name: "open_invoice",
    description: "Open one of the signed-in user's invoices in the app.",
    jsonSchema: {
      type: "object",
      properties: { invoiceId: { type: "string" } },
      required: ["invoiceId"],
    },
    execute: async (args) => {
      const id = typeof args.invoiceId === "string" ? args.invoiceId : "";
      if (!/^inv_[a-z0-9]+$/.test(id)) return "That is not a valid invoice ID.";
      const r = await fetch(`/api/invoices/${id}`); // your backend checks this user may see it
      if (!r.ok) return "That invoice can't be opened.";
      window.location.hash = `#/invoices/${id}`;
      return `Opened invoice ${id}.`;
    },
  },
]);

Page tool safety

The model decides whether to call your tool and with what arguments, and anything in its context can influence it, including knowledge sources and other tools' output.

• jsonSchema is guidance, not validation. Nothing checks the arguments against it before execute runs. Validate them yourself.
• Mindset can't re-authorize a page tool. It runs in your page, so nothing checks that this user may do this thing when the handler runs.

Treat every argument as attacker-controlled. Put nothing behind a page tool (a change, a payment, a read of personal data) unless the handler or your backend checks the user's permission first. The org API key never reaches the browser, and tools that run on Mindset's side still authorize there.

Situational awareness

chat.setSituationalAwareness({
  page: "Invoice detail",
  invoiceId: "inv_4471",
  invoiceStatus: "overdue",
});

Call it whenever the view changes. It is context, not instruction, and it is not a security boundary. What the agent may reach is still decided by Mindset.

Pass-through values

chat.setPassthroughParams({
  "lookup_account.tenantId": "acme-eu",
  region: "eu-west-1",
});

A "tool_name.param" key scopes a value to one tool. A plain param key applies to every tool. Mindset removes those parameters from the tool schemas before the model sees them, and the SDK adds your values to the tool's arguments when the tool is called. The model can't see, choose or guess them.

They stop being hidden if a tool puts the value in its result, because tool results go back to the model. Use pass-through for values the model shouldn't choose, and don't rely on it as a secret channel unless you control what the tool returns.

What isn't possible

• No image attachments on the published client yet.
• No renaming or deleting conversations.
• No Mindset widget renderer is served for the UI-less client. A widget arrives as data (doc, kind and a plain-text summary). Draw it yourself, or show the summary. See widget-payload.