Put the Thinkfree chat UI and agent in your page with one call
You write neither chat UI nor loop. mountChat() from @thinkfree.dev/tfo-ai-sdk/chat renders the Thinkfree chat UI in
an element of your page, creates the agent, and connects Thinkfree Office's document tools. Compare the options in
Choose an integration.
This is the same chat that runs inside Thinkfree Office (progress chips, edit-plan approval, notification cards, the
/tools command), placed wherever your layout needs it. The model follows Thinkfree Office's admin AI Provider settings by
default, or the page chooses it.
mountChat() assembles three layers that are also available on their own: the chat UI component (mountChatUi() from
/ui), the glue (attachSession() from /chat-ui), and the agent (mountHeadless() from /headless, see
Headless agent). The handle exposes all three, so you can adjust any layer with its own API.
| Option 2 | Option 3 | Option 4 (this page) | |
|---|---|---|---|
| Chat UI | Thinkfree | Yours | Thinkfree |
| Loop | Yours | Thinkfree | Thinkfree |
| Code you write | The loop | The chat UI | One call |
The model never touches the document directly. It only picks tools; the agent runs them through Editor SDK in the browser. A relay server forwards model requests, which can include document content read by tools; it never opens or edits the document.
Before you begin
- An open URL for the document. See Document URLs and the
iframe requirements.
mountChat()connects Editor SDK and waits for the Thinkfree Office. AddhideContentBar=1to the open URL so Thinkfree Office's built-in AI Agent panel does not appear next to this chat. - A model. By default Thinkfree Office's admin AI Provider settings are used, so nothing else is needed. To use a different model, pass a relay or direct configuration as described in Connect the model.
- Node.js and npm, and a local static server for the sample page.
Install
npm install @thinkfree.dev/tfo-ai-sdk
The /chat entry contains the chat UI, the glue, the agent, and the Editor SDK document API in one self-contained
bundle (about 1.7 MB). Without a bundler, the import map needs one line. If you copy the bundle files instead of serving
node_modules, keep apiReference.generated.js next to them.
<script type="importmap">
{ "imports": { "@thinkfree.dev/tfo-ai-sdk/chat": "./node_modules/@thinkfree.dev/tfo-ai-sdk/dist/chat.js" } }
</script>
/headless or /ui separately on the same page/chat already contains both, so the runtime would load twice. Use the ui, agent, and session members of the
mountChat() handle instead.
Sample page
Thinkfree Office is on the left and the chat on the right. Save both files, replace YOUR_OFFICE_DOCUMENT_OPEN_URL, and
serve the folder from a local static server.
chat-mount.html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>mountChat: Thinkfree chat UI and agent in my page</title>
<script type="importmap">
{ "imports": { "@thinkfree.dev/tfo-ai-sdk/chat": "./node_modules/@thinkfree.dev/tfo-ai-sdk/dist/chat.js" } }
</script>
<style>
html, body { height: 100%; margin: 0; font: 14px/1.5 system-ui, sans-serif; }
body { display: grid; grid-template-columns: 1fr 420px; }
iframe { width: 100%; height: 100%; border: 0; }
#side { display: grid; grid-template-rows: auto 1fr; border-left: 1px solid #ddd; min-height: 0; }
#status { padding: 6px 12px; border-bottom: 1px solid #ddd; color: #555; font-size: 12.5px; }
#chat { min-height: 0; }
</style>
</head>
<body>
<!-- Office. chat-mount.js sets src to the open URL -->
<iframe id="editor" title="Thinkfree Office document"></iframe>
<!-- mountChat renders the chat UI inside #chat (shadow DOM) and attaches the agent -->
<section id="side">
<div id="status">Preparing…</div>
<div id="chat"></div>
</section>
<script type="module" src="./chat-mount.js"></script>
</body>
</html>
chat-mount.js
import { mountChat } from "@thinkfree.dev/tfo-ai-sdk/chat";
const OPEN_URL = "YOUR_OFFICE_DOCUMENT_OPEN_URL";
const MODULE = "word"; // "word" | "cell" | "show"
const $status = document.getElementById("status");
const editorEl = document.getElementById("editor");
// 1. Open Office. hideContentBar=1 hides Office's built-in AI Agent panel
const editorUrl = new URL(OPEN_URL);
editorUrl.searchParams.set("hideContentBar", "1");
editorEl.src = editorUrl.toString();
// 2. One call: render the chat UI in #chat, create the agent, connect Office's document tools
const chat = mountChat({
el: document.getElementById("chat"),
office: { iframeEl: editorEl, module: MODULE }, // the origin is derived from iframe.src
aiProviderConfig: "office", // default: Office's admin AI Provider settings
ui: { locale: "en" },
agent: { preset: "core" },
onToolCall: (e) => {
if (e.phase === "result") console.log(e.success ? "✓" : "✕", e.name, e.error ?? "");
},
});
// 3. Document tools registered: the chat can now work on the document
chat.ready
.then((toolNames) => {
$status.textContent = `Connected · ${toolNames.length} document tools · ${chat.session.uiToolNames.length} chat UI tools`;
})
.catch((err) => { $status.textContent = `Connection failed: ${err.code ?? ""} ${err.message}`; });
// 4. Clean up: glue -> agent -> UI
window.addEventListener("pagehide", () => chat.destroy());
Expected result: the document opens on the left, the Thinkfree chat on the right, and the status line
shows the number of document tools and 8 chat UI tools. A request such as "Add the heading 'Quarterly summary' at the
top" shows progress chips, an edit-plan card, and a result notification, and the document changes. /tools
lists the registered tools without calling the model.
Options
| Option | Meaning |
|---|---|
el | Required. Element that hosts the chat. The UI renders in shadow DOM, so your CSS does not affect it; it fills the element's height |
office | Thinkfree Office to connect first: { iframeEl, module, frameworkOrigin? }. Omit it to show the UI only and call attachDocument() later |
aiProviderConfig | "office" (default) or a relay or direct configuration |
agent | Agent options: preset (core, review, full; default full), systemPrompt, sessionId, sdkTimeoutMs, readyTimeoutMs |
ui | UI options: locale, messages, variant (default hostChat), fontBase, device, onClose, onPointerDown. See Fit the UI to your page |
session | Glue options: attachment hooks (attachments.intercept, resolveMime), model-facing messages, extra callbacks (onAbort, onClear, onSettingsChange) |
onToolCall | Tool-call listener; same as agent.onToolCall() |
| Handle member | Meaning |
|---|---|
ui, agent, session | The three layers: chat UI component, headless agent, and the glue |
ready | Resolves with the tool names when the first office document is connected; resolves with an empty list at once when office is omitted |
attachDocument(options), detachDocument() | Connect, switch, or disconnect a document. The module shown in the UI follows |
destroy() | Removes everything in order: glue, agent, UI. Idempotent |
Switch documents, observe tools, clean up
// Switch documents: tools are registered again and "office" settings are re-read
chat.detachDocument();
editorEl.src = ANOTHER_OPEN_URL;
await new Promise((r) => editorEl.addEventListener("load", r, { once: true }));
await chat.attachDocument({ iframeEl: editorEl, module: "show" });
// Observe tool calls (same event as the headless agent)
const off = chat.agent.onToolCall((e) => { /* e.phase, e.name, e.success, e.result, e.error */ });
// Put a request into the chat from your own page, for example an "Ask AI" button
chat.ui.triggerInput("Add the heading 'Quarterly summary' at the top");
// Clean up
chat.destroy();
- The agent's session keeps the conversation history. The chat header's reset button starts a new conversation; in code,
destroy()and callmountChat()again. chat.session.bridgeis the chat UI bridge behind the UI, withnotify(),setSettings(),triggerInput(), and the rest of its API.
Fit the UI to your page
- Language and text.
ui.localehasenandkobuilt in. Override any string, or add another language, withui.messages. - Font. The bundle includes no font files and inherits the page font. To use Pretendard, set
ui.fontBaseto a directory URL with its woff2 files; one@font-faceis added to the document head. - Close button. The default
variant: "hostChat"has no close button. If your page can collapse the panel, usevariant: "embedded"with anonClosehook. - Tablet.
ui.device: "tablet"widens touch spacing. It is not detected automatically. - Style isolation. Your page CSS does not reach inside the shadow DOM.
ui.noShadow: trueturns isolation off; it is not recommended.
Rules
- The model receives prompts, history, tool schemas, and tool results, including document content read by tools. Decide what may leave the browser; see Safety.
- Edits already applied are not rolled back. In the default edit-accept mode the user reviews large edits in an edit-plan card first.
/chatis about 1.7 MB. If the first load is heavy, load it with a dynamicimport()when the user opens the chat.
Troubleshooting
| Symptom | Check |
|---|---|
| The chat area is empty | mountChat() threw, or el has zero height. Check the console and give the element a height. |
ready rejects with TIMEOUT | The open URL is not an open URL, or Thinkfree Office runs on a different origin than the iframe src. See Document URLs. |
| Provider error on the first send | With "office", Thinkfree Office has no admin AI Provider settings. With an object, see Headless agent troubleshooting. |
| The font differs from the page | The bundle has no font files. Set ui.fontBase, or keep the page font. |
/headless is also imported | The runtime loads twice. Remove the separate import and use chat.agent. |
| The model answers without using tools | Be specific, and narrow the tools with agent: { preset: "core" }. |