Skip to main content
A chat beside an editable .docx: a Mastra agent edits the document through Vespper, and its edits appear in EigenPal’s docx-editor as tracked changes.

​
What the example includes

  • Suggestion cards to review, edit, and apply the agent’s edits
  • Live document updates through the docx-editor document refresh API
  • Selected text and pasted images as prompt context
  • Multi-model selection

​
Prerequisites

  • Node.js 22.13 or newer
  • A Vespper account
  • A model-provider API key for OpenAI, Anthropic, or Google

​
Set up the example

1

Get a Vespper API key

Sign up for Vespper, then create a key on the API keys page. Copy the sk_live_... secret immediately; it is shown only once.
2

Install the example

Clone the repository, then install the dependencies:
Edit .env and add your Vespper key plus the key for the model provider you want to use:
.env
Only one model-provider key is required:OpenAI GPT 5.6 Sol is the default. To start with another model, set DOCX_AGENT_MODEL in .env, for example:
.env
By default, the agent proposes edits as suggestion cards that you accept or reject. To have it apply edits to the document as it writes them, set:
.env
3

Run it

This starts the API server at http://localhost:3001 and the web app at http://localhost:5173. Vite proxies /api and /health to the API server.

​
Try an edit

  1. Drop a .docx onto the right pane.
  2. Ask the AI agent for an edit.
  3. Optionally select text in the document to include it as context, or paste images into the prompt.
With suggestions on, each edit appears as a card in the chat while the agent writes it. Edit a card’s text if you want, then accept or reject it, or use Apply all. Accepted edits land in the document as tracked changes and are briefly highlighted. The agent is told which suggestions you accepted, edited, or rejected on the next turn. With suggestions off, the agent’s edits stream into the document as tracked changes while it works.

​
How it works

The API server follows Vespper’s live-editing architecture: it runs an agent with the Vespper tools and handles each old/new pair of an edit_document call as soon as the model finishes writing it.
  • Suggestion mode (the default): each pair is proposed to the user in the chat as a suggestion card, without changing the document. Accepted cards go to POST /api/apply, which applies them. See Suggestions.
  • Direct mode (USE_SUGGESTIONS=false): each pair is applied right away.
In both modes, every change to the document reaches the browser as an edit_applied event that carries the complete, cumulative .docx and its revision number.

​
Updating the editor

The browser loads each new file through the docx-editor document refresh API, for both agent turns and Apply:
  1. refresh.capture() snapshots the document that goes to the server.
  2. Each edit_applied event calls refresh.applyUpdate(), which swaps in the new file and keeps the scroll position.
  3. refresh.highlightChanges() flashes the new tracked changes.
  4. refresh.finish() closes the update.
The document is read-only while an update runs. The code is in src/agent/updateQueue.ts.

​
Development commands

​
Project layout

​
Licensing

This example is MIT licensed. It depends on @docx-editor.dev/pro for tracked-change rendering and the review rail, which is distributed under the EigenPal Pro Evaluation License: internal, non-production evaluation only. Contact EigenPal for a production license. Without the review module, docx-editor shows revisions in their accepted state and keeps them in the saved file.

View the complete example on GitHub

Browse the source code and standalone README.