A copilot on your site

The copilot is a chat widget for your own site or app. Its answers are grounded in your map: every question is resolved against what you published, and every answer carries one of the three outcomes from the Overview — serve, ask, or none. That last one is the feature. A visitor who asks something your system does not cover gets "I don't know that" instead of an invention, which is what makes it safe to put on a pricing page.

Each section below names the API route behind the product step, for the record and for agents working beside you. One honest boundary: these setup routes answer to your signed-in session, not to an API key, so today the setup happens in the product or by an agent driving a signed-in browser. Key minting and provider connection stay that way on purpose. An agent that needs credentials asks through the device flow, and you approve it with one click in your workspace.

Create an agent#

In the app, open Agents. Pick a template (Docs & Answers is the usual first one) and press Create agent, or press Discover agents and Sioma proposes agents that fit what your map actually supports.

Creating it sets its scope: what it can see, what it can do, which model answers, and its own key. Everything a card offers is derived from your map, never promised.

API: GET /api/agents lists your agents, POST /api/agents creates one, PUT /api/agents/{id} edits it. Minting the agent's key (POST /api/agents/{id}/key) requires a signed-in person.

Put it on a page#

The agent's Use panel prints your exact snippet. It looks like this:

import { createCopilot } from "@sioma/copilot";
import { mountCopilot } from "@sioma/copilot/ui";

const copilot = createCopilot({
  cellUrl: "https://aws-us1.cells.sioma.ai",
  platformUrl: "https://app.sioma.ai",
  tenant: "your-workspace-hint",
  agent: "agt_1a2b3c4d",
});

mountCopilot(document.getElementById("copilot"), copilot, {
  title: "Docs & Answers",
});

Install the package with npm install @sioma/copilot. There is no other setup: no server of yours, no proxy, no environment variables.

Everything in the snippet is public by design. The two identifiers name your workspace and the agent; the widget exchanges them for short-lived tokens on the Sioma side, scoped to that one agent. No key of any kind is in the page, and nothing secret ever reaches the browser.

What actually bounds abuse, since the ids are public: each token carries the agent's signed scope, requests are rate limited per agent and per workspace, and the widget only runs on domains you listed. Deleting the agent, or replacing its key, kills every outstanding embed token within a minute.

Where it runs#

The widget loads only on domains you declared. On the same Use panel, under Where your copilot runs, add your site's origin, for example https://your-site.com. It applies to every agent in your workspace, usually within a minute, and removing a domain shuts the widget off there just as fast.

Exact addresses only: scheme, host, and an optional port. No wildcards, so a subdomain you did not list stays off.

One honest note: the domain list controls where a browser may run the widget. It is not what protects your data. The token's scope and the per-agent caps are.

API: GET /api/origins reads the list, PUT /api/origins replaces it (workspace admin).

Choosing the model#

Answers are generated by your workspace's AI provider. Connect one under Control room → Configure: Sioma's managed default, or your own account (Anthropic, OpenAI, Vertex, Bedrock, Azure). Each agent can pin its own model on its card. Changing either applies to the next question, with no redeploy and no snippet change.

If you want answers generated on your own infrastructure, pass a model to createCopilot (any AI SDK v7 model). That replaces the Sioma-side model call entirely. It is the escape hatch, not the default.

What makes answers good#

The copilot answers from your map, so the map is the product:

• Publish real content. A spec with real fields, docs pages with real explanations. A copilot grounded on three slogan pages is a polite way of saying nothing. Your API map alone makes answers endpoint-shaped; add your docs with npx @sioma/cli scan --docs ./docs and the copilot answers in your own prose — see Map your system.
• Turn on meaning matching if your visitors phrase things freely. It matches questions by meaning rather than exact wording, at the cost of one embedding call per question. It is off by default; the toggle is in the app.
• Ask it real questions. Measure with the questions your users actually ask, not the ones you invented. The Review page shows you what was served and lets you rule on it, and your rulings change what gets served next.

The limits, stated plainly#

• It answers from what you published and nothing else. An empty map produces a polite but useless copilot.
• It will answer none rather than guess. That is deliberate and not configurable away.
• The conversations are yours. Sioma measures outcomes to improve serving; it does not train on your content.