Host embed

Directory: sdk/host-embed Who this is for: third parties who put a Cadau embed assistant into their own business system. This folder is a complete handover pack.

Handover: this directory (sdk/host-embed/) is the main doc pack for third-party integration (overview, contract, website integration, knowledge writing, HR walkthrough, legacy-host enhancement). Give this folder to the integrating team and they can start. Runnable full-stack examples and some mechanism source-of-truth still live elsewhere in the repo (see the links below); those links break if you copy only this folder.

Audience: teams embedding a Cadau conversation assistant in their own system (ERP, OA, industry SaaS, and similar) — business admins, backend and frontend developers, and ops.

After this page you can: mount the assistant on a host page, assign different agents per signed-in user, let the assistant guide people to open business pages from the reply, and confirm that signed-in users cannot see each other's conversation history, live support, or tickets.

Technical contract (fields, SSE, error codes): Embed contract (V1.5.12). Copy-paste frontend notes: Website integration. Path A static example: examples/cadau-embed-site/. Path B full-stack example: examples/hr-multi-tenant/ and HR embed example.

Sibling SDKs: appsdk · platform-plugin · agent-capability · this directory. Overview: sdk/README.md.

Note: the script the browser loads is still /embed/mindlink-widget.min.js on the site (HTTP route; independent of this doc folder name).

Documents in this directory

1. What you get

On your business pages:

• A conversation assistant in the bottom-right corner (or inline), talking to a Cadau My agent you already configured;
• Conversation goes through the Cadau server, so you can gate access, audit, and revoke;
• The assistant can put clickable navigation links in replies; one click opens the matching page in your system with filters (for example “pending orders” or “this employee’s file”);
• When the user says “open such-and-such page for me”, the widget can run the first registered navigation automatically after the reply finishes (you can turn this off; see §8.3).
• (Optional) The host backend can also ask a chosen agent to answer (approval summaries, suggest jobs by department, and similar — the user need not see the widget). See Host LLM service.

Cadau does not own: your sign-in users, business permissions, or business database. Who the user is and which menus they see is still the host system’s job.

2. Who does what

flowchart LR
  subgraph ML["Cadau (agent provider)"]
    UA["Configure agents and knowledge"]
    ET["Issue embed access tokens"]
    CHAT["Conversation and retrieval"]
  end

  subgraph Host["Third-party host (your system)"]
    ADM["Register agents, assign users"]
    BFF["Backend mints tokens"]
    UI["Business page + conversation widget"]
  end

  ADM --> BFF
  BFF -->|"integration account"| ET
  UI -->|"short-lived token"| CHAT
  UA --> CHAT

3. Which of the two paths to use

Recommendation:

• Any website, no business sign-in → use A; static walkthrough: examples/cadau-embed-site/.
• Real business system, assign by user, tokens not in the frontend repo → use B (HR example: HR embed example).

Minting (B): the host backend uses a Cadau integration account to call POST /api/v1/user-agents/{agentId}/embed-token, then hands the short-lived embed token to the browser. End users do not sign in to the Cadau main site.

4. Cadau-side prep (agent owner)

Before you change the host, finish this table in Cadau (align with the host side first if needed):

Path B does not need you to click “generate token” in Cadau for every host user. The host backend mints with the same API as the UI button.

(Path A required) On that assistant, Manage → Website embed generate a token. The page only needs site URL + agent ID + token (no workspace ID). For widget “Live support” and “Submit a ticket”, turn them on under the same agent’s Live support, and assign seats in this workspace or authorize a support team (when nobody is on duty, only submit-ticket remains). Full copy can be taken from Copy website integration notes on that page.

5. Host side: what admins do

In your admin UI (or ops scripts):

5.1 Register agents to connect

Create one registration row per Cadau agent you will connect. Store the agent ID only, not the embed token:

(Optional) generate/analyze agent: when the host backend runs jobs such as “suggest jobs”, point at another agent already configured in Cadau — MINDLINK_GENERATE_USER_AGENT_ID in .env, or pick it on the “embed assistant registry” admin page (overrides the env var). This is not the bottom-right conversation assistant. See Host LLM service §5.1.

5.2 Assign by signed-in user

• The assignment subject is the host signed-in user (the account behind a phone / employee number), not the employee file id (unless they are the same).
• For each user choose: which registration row, and which operation scopes (query only, whether create/edit/delete is allowed — host-defined enums).
• Users with no assignment: the business page does not show the assistant, or the embed-session API returns “no assistant yet”.

HR multi-tenant example: sidebar User management → Connected agents / Configure agent; details in HR embed example §8.

6. Host side: developer checklist

6.1 Data layer (path B)

At least two tables (names are yours):

1. Registered agents (§5.1 fields)
2. User–agent assignments (tenant + user → registration row + permission scopes)

6.2 Embed-session API (path B core)

Provide an API like this (path is yours; keep the meaning):

GET /api/v1/.../me/embed-session
Authorization: Bearer <host sign-in token>

Server logic:

1. Confirm the host user is signed in;
2. Look up whether they have a valid assignment;
3. No assignment → return 200, body with available: false and a reason (do not use 404, which browsers treat as a hard error);
4. Has assignment → sign in to Cadau with the integration account → switch workspace → call

POST /api/v1/user-agents/{agentId}/embed-token body example: { "app_id": "your-app", "ttl_seconds": 3600 };

1. Return these fields to the frontend (names may match the example):

Integration-account password and Cadau internal URL live only in server env vars. Do not commit them to the frontend repo.

Cadau mint order (server calls, not the browser):

POST /api/v1/auth/login
POST /api/v1/workspaces/{workspaceId}/switch
POST /api/v1/user-agents/{userAgentId}/embed-token

6.3 Mount the widget on the frontend

1. The user opens a business page that should have the assistant;
2. (B) Request embed-session with the host sign-in token; or (A) read static config;
3. Load widget_script dynamically;
4. Initialize:

<script src="https://<Cadau host>/embed/mindlink-widget.min.js"></script>
<script>
  const widget = window.MindLinkWidget.init({
    app_id: "your-app-id",
    api_base_url: "https://<public API prefix>/api/v1",
    user_agent_id: "<agent UUID>",
    workspace_id: "<workspace UUID>",
    auth: {
      token: "<embed access_token>",
      expires_at: "<ISO 8601>"
    },
    // Path B required: same host_actor as embed-session (isolates history / support / tickets; also host data queries)
    // The widget sends X-Host-External-User-Id automatically; the host page does not set that header
    host_actor: { external_user_id: "…", actor_kind: "employee" },
    theme: "auto",
    position: "bottom-right",
    locale: "zh-CN",
    entry: {
      auto_open: false,
      auto_execute_navigation: true
      // hide_launcher: true skips the corner button; a host button calls widget.open()
    }
  });

  widget.on("action", function (ev) {
    if (ev.type !== "action") return;
    handleHostNavigation(ev.action);
  });
</script>

1. Before the token expires: mint again on the backend, then widget.updateAuth({ token, expires_at }). When the signed-in user changes, widget.updateHostActor(hostActor) (or init again).

Inline embed: position: "inline" + container: "#your-container-selector". Web Component: see Website integration §4.1.

Reference code (in the Cadau repo; not part of this folder handover):

• HR example mount: examples/hr-multi-tenant/web/src/mindlinkOrgEmbed.ts
• HR example navigation: examples/hr-multi-tenant/web/src/mindlinkHostActions.ts

6.4 Network and security

Server env example (path B):

MINDLINK_API_BASE=https://mindlink.internal/api/v1
MINDLINK_API_BASE_PUBLIC=https://your-host.com/mindlink-api/v1
MINDLINK_WIDGET_SCRIPT=https://mindlink.internal/embed/mindlink-widget.min.js
MINDLINK_INTEGRATION_EMAIL=integration@your-corp.com
MINDLINK_INTEGRATION_PHONE=
MINDLINK_INTEGRATION_PASSWORD=<server only>
MINDLINK_APP_ID=your-corp-app
MINDLINK_WORKSPACE_ID=<workspace UUID shared by the whole host>
MINDLINK_GENERATE_USER_AGENT_ID=<optional: generate/analyze agent UUID>

Embed token TTL and whether the widget is inline have code defaults; they need not go in .env. The integration account can sign in to Cadau with email or phone (same as the HR example server/.env).

7. In-reply navigation: let the assistant open business pages

7.1 How it works

1. In the agent knowledge documents, agree: when a jump is needed, use a Markdown link with protocol mindlink://action/;
2. The user clicks the link (or the widget fires it when auto-navigation is on) → the host page receives an action event;
3. The host page whitelists the action name and params, then routes or opens a drawer.

7.2 Link syntax (put this in knowledge documents)

`Open pending orders`
`View org chart`

• Action name: a business action you register on the host page; prefer page.<module>;
• Query params: passed through to the host page (status, id, label, and similar); label may be display-only.

7.3 Host-page whitelist (required)

const HOST_ACTIONS = {
  "page.orders": (params) => {
    app.navigate("/orders", { status: params.status || "" });
  },
  "page.org": (params) => {
    app.navigate("/org", { tab: params.tab || "tree" });
  },
};

function executeHostAction(action, params) {
  const fn = HOST_ACTIONS[action];
  if (!fn) {
    app.toast("This navigation is not supported yet");
    return;
  }
  fn(params);
}

Do not run unsafe protocols such as javascript:. Unknown actions should say “not supported yet”.

7.4 Auto-navigation

entry.auto_execute_navigation defaults to true: when the user clearly says “open / jump to…”, after the streamed reply ends the widget automatically runs the first host-executable mindlink://action/ link in the body (same filter as clicks). To require a manual click, set it to false.

Knowledge documents must say: when the user asks to open a page, put 1–3 registered links at the end of the reply, and the first host-executable link must be the most relevant target.

Writing spec: Host knowledge writing.

8. Recommended rollout order

8.1 Automated smoke (HR example)

A smoke test is a scripted minimum integration check in real API order: no browser, fail fast on any step. Use it after config changes or a release to confirm “we can even start testing”.

In examples/hr-multi-tenant/web (Cadau :8080 and HR backend :18089 already running, server/.env has MINDLINK_*):

Not a substitute for full acceptance: SQLite data connections, writing access policy, and UI still need a manual pass (HR example: examples/hr-multi-tenant/docs/ACCEPTANCE_HOST_LEGACY.md in the repo).

8.2 Local HR example

# See examples/hr-multi-tenant/README.md
cd examples/hr-multi-tenant/web
npm run setup:mindlink    # registers the integration account and writes ../server/.env
cd ../server && go run ./cmd/hrms-server   # separate terminal
cd ../web && npm run dev
# Browser http://localhost:5180 ; demo login 13800138000 / Demo-HR-2026
npm run smoke:embed         # optional: embed smoke
npm run smoke:host-agent    # optional: legacy-host enhancement smoke

Register an existing Cadau agent into the HR example:

cd examples/hr-multi-tenant/web
npm run link:mindlink-agent -- <MindLink agent UUID>

Note: link:mindlink-agent reads/writes local SQLite backend/mindlink.db by default. If Cadau’s main DB is Postgres (common in local development), invite the integration account into the workspace in the Cadau UI, and check mindlink_workspace_id on the registration row; or re-run setup:mindlink.

9. Observability: how the agent owner sees embed conversations

Embed conversations are stored under the Cadau identity used to mint, and do not appear in that identity’s personal Messages list.

The agent owner on the Cadau main site:

1. My agents → Run history;
2. Pick the assistant on the left;
3. Source: Embed (filter by app id);
4. Open a conversation read-only.

From the agent Manage → Overview you can click View run history to jump to that assistant’s embed records.

10. Integration and acceptance checklist

Cadau

• [ ] Agent created, knowledge documents mounted (including the list of pages that can be opened)
• [ ] app_id matches the host
• [ ] B: integration account can sign in, is in the agent’s workspace, and can mint
• [ ] Workspace ID on the registration row matches the agent’s real workspace (this phase: the whole host shares one Cadau workspace)
• [ ] (Optional) that agent has Live support on (seats in this workspace or an authorized support team); support covering this workspace is on duty; the widget shows “Live support / Submit a ticket”

Host backend

• [ ] Register and assign APIs work
• [ ] Assigned users: embed-session returns available: true and access_token
• [ ] Unassigned users: available: false (HTTP 200)
• [ ] Integration password is not in the frontend or a public repo

Host frontend

• [ ] After sign-in the assistant appears and can stream a conversation
• [ ] When different users are assigned different agents, conversation identity is correct (B)
• [ ] (B) init received host_actor; two signed-in users cannot see each other’s history, live support, or tickets
• [ ] (A) two website visitors cannot see each other’s history, live support, or tickets (a new browser or cleared site data is a new visitor)
• [ ] Two visitors can ask at the same time and each get a reply; when overloaded the widget says “Too many people talking right now. Try again in a moment.”
• [ ] Before the token expires, updateAuth or re-entering the page can mint again
• [ ] (Optional) navigation links in replies jump correctly; auto-navigation matches expectations
• [ ] Unknown navigation has a friendly message

Legacy-host enhancement (if you connect Host Agent Run / business-DB queries)

• [ ] Host BFF sends a complete host_actor on embed-session / agent-run
• [ ] Workspace data connection is configured and access_policy_json is written
• [ ] Employee self-service sees only their own rows; manager/admin scope matches expectations; conversations do not leak across users
• [ ] (Optional) npm run smoke:host-agent passes

Security and ops

• [ ] Production is mainly B; A is dev-only
• [ ] Cadau API is same-origin proxied or CORS is compliant
• [ ] Integration-account rotation and token revoke are documented
• [ ] Production uses a self-created integration account, not the HR example demo email

11. FAQ

12. Document index (this directory)

13. Maintenance