The Server Agent

An AI assistant that does not export your data to a chat window. It works on the live spreadsheet, with tools, under the same rules as your users, and every change it makes reaches everyone on the document.

Published on October 5, 2026

Introducing

@jspreadsheet/server-agent adds an AI chat to Jspreadsheet Server. A user asks for something in plain language, "add a total per region", "highlight the overdue tasks", "build a chart of Q2 by product", and the agent does it: it reads the document, decides on the steps, and calls spreadsheet tools until the job is done, streaming its answer as it goes.

Because the server owns the live document, the agent is not working on a copy. Its edits go through the same pipeline as a person's: validated by your hooks, applied to the document, persisted by your adapter and broadcast to every connected browser.

How it works

The document is the context

Every prompt carries a description of the open workbook: worksheets, columns, data and formulas. The model answers about the numbers that are actually there, not about an export from an hour ago. The part of the context that does not change between turns is cached, so a long conversation does not pay for the document again on every message.

Tools, not text

The agent changes the spreadsheet through more than 20 tools that map onto the Jspreadsheet API:

• Data: setValue, setData, setRowData, setColumnData, paste, and reading with getData and getConfig.
• Structure: insertRow, deleteRow, insertColumn, deleteColumn, createWorksheet, setHeader, setColumnProperties, setCellProperties.
• Presentation: setStyle, resetStyle, setFilter, and setMedia / deleteMedia for charts, images and shapes.
• History: undo and redo.

Formulas are written as formulas, so the result stays live: ask for a total and the cell holds =SUM(B2:C2), not a number that goes stale.

Attachments

Users can attach files to a message. Spreadsheets are read with SheetJS, PDFs are converted to text, and images are shown to the model on demand through the viewImage tool, so "put the table from this screenshot into Sheet2" works.

Built for production

Opening a model to your users is a cost decision as much as a feature. The agent leaves every policy to you through small hooks:

• allow(guid, auth, request) runs before a prompt reaches the model. Return false, or a message, and the request is refused with HTTP 429 before anything is spent. The request carries the caller's address, the prompt and the size of the attachments.
• usage.set(guid, usage, auth, request) receives the token usage of every model call, split into input, output and cache reads and writes.
• prompt stores the conversations, in sessions, wherever you keep data.

Together they make quotas a few lines of code: count tokens per user or per address in usage.set, refuse in allow once the daily budget is used. The package README has a complete Redis example with a per-address limit, a site-wide budget and a rate limit.

const agent = require('@jspreadsheet/server-agent');

agent({
    allow: async (guid, auth, request) => await quota.check(request.ip),
    usage: { set: async (guid, usage, auth, request) => quota.add(request.ip, usage) },
});

server({
    // ...
    extensions: { api, agent },
});

The model is a setting: CLAUDE_MODEL=claude-haiku-4-5 for a fast and economical assistant on a public page, a larger model for heavier analysis.

Where you see it

The Intrasheets AI assistant is a client of the agent: a chat pane next to the workbook, with sessions, attachments and streamed answers. Any application can call the same route, POST /api/<guid>/prompt, and render the stream its own way.

For AI clients that live outside your application, such as Claude Code or an IDE assistant, the MCP server exposes the same documents and the same rules through the Model Context Protocol.

Useful links

Server Agent documentation
AI with Jspreadsheet Server
Intrasheets demo