Install matching packages
npm install @onodocs/editor
npm install https://github.com/onodocs/onodocs/releases/download/sdk-v0.5.13/onodocs-agent-0.5.13.tgzAgent is currently distributed through the GitHub release archive. Use the matching SDK/Canvas/Editor release; release notes list the current versions. Agent is a commercial optional package under the same application scope as the SDK. Your model provider bills model usage separately.
Mount the assistant beside the editor
import { createEditor } from "@onodocs/editor";
import { createAgent, agentRibbonCommand, createHttpTransport, createEditorApiBridge } from "@onodocs/agent";
let agent;
const editor = createEditor({
container: document.querySelector("#document"),
commands: [agentRibbonCommand(() => agent?.toggle())]
});
await editor.open(bytes);
agent = createAgent({
container: document.querySelector("#assistant"), editor,
transport: createHttpTransport("/api/agent", { credentials: "same-origin" },
() => createEditorApiBridge(editor, authorizeDocumentCall))
});Supply two empty, sized hosts, document bytes and an authorization callback for document calls. The AI Agent button appears before Undo. Your backend implements /api/agent; it is not an OnoDocs hosted API. On unmount, dispose the Agent and editor. Use existing application change handlers and autosave.
Provide a model backend
@onodocs/agent/server exposes runAgentTurn, agentEventResponse and bridge/accounting contracts. @onodocs/agent/openai supplies createOpenAIProvider({ apiKey, model }). Keep keys on the backend. Authenticate users, authorize documents and methods, serialize turns and deduplicate stable request IDs.
The turn host requires reservation, settlement and conversation-commit callbacks. Reserve capacity before each model continuation and retain reservations for uncertain charges. The complete Node example includes a transport, persistent usage ledger, authorization and cleanup. It is the starting point for a running integration, rather than a permissive no-op accounting callback.
git clone https://github.com/onodocs/onodocs.git
cd onodocs
npm install
npm run example:agentProvide OPENAI_API_KEY in the server environment before starting; do not place it in a browser module. Open the printed local URL. The local example allows browser-owned documents and authorized TXT/DOCX attachments; replace its demonstration trust and identity model for your production service.
Configure the Agent
The Agent configuration guide covers provider and model selection, application instructions, additional tools, permissions, limits, context and interface customization.
Document tools and Undo
The model discovers current public API declarations through api_read. api_script inspects and edits through document, editor and view APIs in an isolated worker. It has no network, storage or host JavaScript access. Serve its worker and chunks, with CSP permitting the worker and WebAssembly.
Use createEditorApiBridge so edits participate in editor history, rendering, change notifications and autosave. Reacquire query results after edits. Optional page-image inspection needs host configuration. A data-only server cannot supply browser presentation or scripting unless the host provides those capabilities.
Stop cancels further work; completed changes can remain after Stop or a later tool failure. Review the actual result and use Undo for unintended edits. Document text and attachments are untrusted data, never permission to perform unrelated actions.
Data flow and attachments
Requests send the prompt and selected/required document context to your backend and configured provider. Image context additionally sends a page image. Hosts own retention, logs, authorization, upload limits and attachment deletion. Attachments are session-authorized references and do not silently replace the editable document.
Ordinary Editor use does not require a model service. Offer an explicit choice before starting assistance and explain your provider and retention policy.
Try the hosted sample
Open the document Agent demo. It opens fictional samples in the browser and uses the same Agent connection as the main editor, including API scripts and Undo/Redo. Attachments are disabled. Download your edited document to keep changes; reloading opens the original sample.
Messages and required context are sent to the configured model service. Session data expires after 24 hours; usage records enforce a finite shared demo allowance. AI work may be unavailable after the allowance is used. See the demo data disclosure. Use fictional information in prompts.