Skip to main content

Put the Thinkfree chat UI and agent in your page with one call

Integration option 4

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 2Option 3Option 4 (this page)
Chat UIThinkfreeYoursThinkfree
LoopYoursThinkfreeThinkfree
Code you writeThe loopThe chat UIOne 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. Add hideContentBar=1 to 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>
Do not import /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​

OptionMeaning
elRequired. Element that hosts the chat. The UI renders in shadow DOM, so your CSS does not affect it; it fills the element's height
officeThinkfree 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
agentAgent options: preset (core, review, full; default full), systemPrompt, sessionId, sdkTimeoutMs, readyTimeoutMs
uiUI options: locale, messages, variant (default hostChat), fontBase, device, onClose, onPointerDown. See Fit the UI to your page
sessionGlue options: attachment hooks (attachments.intercept, resolveMime), model-facing messages, extra callbacks (onAbort, onClear, onSettingsChange)
onToolCallTool-call listener; same as agent.onToolCall()
Handle memberMeaning
ui, agent, sessionThe three layers: chat UI component, headless agent, and the glue
readyResolves 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 call mountChat() again.
  • chat.session.bridge is the chat UI bridge behind the UI, with notify(), setSettings(), triggerInput(), and the rest of its API.

Fit the UI to your page​

  • Language and text. ui.locale has en and ko built in. Override any string, or add another language, with ui.messages.
  • Font. The bundle includes no font files and inherits the page font. To use Pretendard, set ui.fontBase to a directory URL with its woff2 files; one @font-face is added to the document head.
  • Close button. The default variant: "hostChat" has no close button. If your page can collapse the panel, use variant: "embedded" with an onClose hook.
  • 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: true turns 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.
  • /chat is about 1.7 MB. If the first load is heavy, load it with a dynamic import() when the user opens the chat.

Troubleshooting​

SymptomCheck
The chat area is emptymountChat() threw, or el has zero height. Check the console and give the element a height.
ready rejects with TIMEOUTThe 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 sendWith "office", Thinkfree Office has no admin AI Provider settings. With an object, see Headless agent troubleshooting.
The font differs from the pageThe bundle has no font files. Set ui.fontBase, or keep the page font.
/headless is also importedThe runtime loads twice. Remove the separate import and use chat.agent.
The model answers without using toolsBe specific, and narrow the tools with agent: { preset: "core" }.