Skip to main content
The Word add-in example combines Office.js, React, Mastra, and the Vespper TypeScript SDK to edit the document currently open in Microsoft Word. It follows Word’s Track Changes setting: tracking-on edits remain reviewable, while tracking-off edits are applied directly.

​
What the example includes

  • Streamed edits: Apply cumulative document revisions while the agent is still working, with or without visible tracked changes.
  • Document sessions: Upload the DOCX once, use a session ID for every tool call, and clean up the session after each agent turn through the Vespper SDK.
  • Document context: Send selected Word content and pasted images alongside the user’s request.
  • Agent controls: Choose a model, stop an active run, and set the tracked-change author.

​
Demo

​
Prerequisites

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

​
Set up the add-in

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

Clone and install the example

3

Configure environment variables

Copy the environment template:
Add your Vespper key and the key for the model provider you want to use:
.env
Only one model-provider key is required:GPT 5.6 Sol is the default. Set WORD_AGENT_MODEL to start with another model:
.env
4

Trust the local HTTPS certificate

Office add-ins require HTTPS, including during local development:
5

Launch Word

This builds the task pane, starts the local server at https://localhost:3100, launches Word, and sideloads the add-in. If the task pane does not open automatically, choose Home → Add-ins → Vespper.Open https://localhost:3100/health and confirm that both vespperConfigured and agentConfigured are true.

​
Try an edit

  1. Open and save a Word document.
  2. Open the Vespper task pane.
  3. Ask for an edit, such as Replace every occurrence of DFAT with Hello.
  4. Optionally select document text or paste images into the prompt.
  5. When Track Changes is on, review the streamed edits under Review → Track Changes.
Use the settings button to change the tracked-change author used while tracking is on from the default Vespper Agent.

​
How the integration works

The local API server opens a document session and auto-patches Mastra’s Vespper tools with the vespper SDK. The SDK supplies session, author, and tracked-change metadata and retains each updated DOCX revision. The add-in wraps the patched edit_document tool to parse edits while the model is still producing its arguments. That wrapper adds the streaming batch ID and edit index, while the SDK continues to handle the standard Vespper metadata. Each committed revision is then sent to Word as an edit_applied event.

​
Development commands

View the complete example on GitHub

Browse the source code, manifest, and standalone README.