> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vespper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Word add-in

> Build a Microsoft Word add-in that streams AI-generated edits into the open document.

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

<Frame>
  <iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/xuJ7OsZ5I04" title="Vespper Word add-in live-editing demonstration" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</Frame>

## Prerequisites

* Microsoft Word desktop for macOS or Windows
* Node.js 22.13 or newer
* A [Vespper account](https://app.vespper.com)
* A model-provider API key for OpenAI, Anthropic, or Google

## Set up the add-in

<Steps>
  <Step title="Get a Vespper API key" titleSize="h2">
    [Sign up for Vespper](https://app.vespper.com), then create a key on the
    [API keys page](https://app.vespper.com/keys). Copy the `sk_live_...`
    secret immediately; it is shown only once.
  </Step>

  <Step title="Clone and install the example" titleSize="h2">
    ```bash theme={"system"}
    git clone https://github.com/vespperhq/examples.git
    cd examples/word-add-in
    npm install
    ```
  </Step>

  <Step title="Configure environment variables" titleSize="h2">
    Copy the environment template:

    <Tabs sync={false}>
      <Tab title="macOS or Linux">
        ```bash theme={"system"}
        cp .env.example .env
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={"system"}
        Copy-Item .env.example .env
        ```
      </Tab>
    </Tabs>

    Add your Vespper key and the key for the model provider you want to use:

    ```bash .env theme={"system"}
    VESPPER_API_KEY=sk_live_your_key_here
    VESPPER_MCP_URL=https://mcp.vespper.com/mcp

    OPENAI_API_KEY=sk-your_openai_key_here
    ```

    Only one model-provider key is required:

    | Model family | Environment variable |
    | - | - |
    | OpenAI GPT | `OPENAI_API_KEY` |
    | Anthropic Claude | `ANTHROPIC_API_KEY` |
    | Google Gemini | `GOOGLE_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY` |

    GPT 5.6 Sol is the default. Set `WORD_AGENT_MODEL` to start with another
    model:

    ```bash .env theme={"system"}
    WORD_AGENT_MODEL=anthropic/claude-sonnet-4.5
    ```
  </Step>

  <Step title="Trust the local HTTPS certificate" titleSize="h2">
    Office add-ins require HTTPS, including during local development:

    ```bash theme={"system"}
    npm run setup:certs
    ```
  </Step>

  <Step title="Launch Word" titleSize="h2">
    ```bash theme={"system"}
    npm start
    ```

    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](https://localhost:3100/health) and
    confirm that both `vespperConfigured` and `agentConfigured` are `true`.
  </Step>
</Steps>

## 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

| Command | Purpose |
| - | - |
| `npm start` | Build, serve, launch Word, and sideload the add-in |
| `npm stop` | Stop and unregister the sideloaded add-in |
| `npm run dev` | Build and serve without launching Word |
| `npm run typecheck` | Type-check the server and task pane |
| `npm run build:addin` | Build the task-pane assets once |
| `npm run setup:certs:check` | Verify the local HTTPS certificate |

<Card title="View the complete example on GitHub" icon="github" href="https://github.com/vespperhq/examples/tree/main/word-add-in" horizontal>
  Browse the source code, manifest, and standalone README.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.