office-agents: AI chat panels inside Word, Excel and PowerPoint

Three add-ins over one shared runtime

Office Agents is a monorepo of Microsoft Office add-ins with integrated AI chat panels, and the structure of the packages tells you how the pieces divide. There is @office-agents/sdk, described as a headless SDK holding the agent runtime, tools, storage, the VFS, skills, OAuth and web search. There is @office-agents/core, the chat user interface built with Svelte 5, which re-exports the SDK plus the chat components, settings and sessions. There is @office-agents/bridge, a local HTTPS and WebSocket RPC bridge with a CLI for inspecting a live Office add-in runtime. And then the three add-ins themselves, @office-agents/excel with spreadsheet tools, Office.js wrappers and a system prompt, @office-agents/powerpoint with slide and OOXML tools, and @office-agents/word with document text, structure and OOXML tools. Each add-in connects to major LLM providers using your own credentials, which the description abbreviates as BYOK, and can read and write documents through built-in tools, a sandboxed shell and a virtual filesystem. So the interesting architecture is that the AI runtime lives once in a headless SDK, the interface is a Svelte chat panel, and each Office application gets a thin add-in that supplies the document specific tools and the prompt that tells the model what it is looking at.

BYOK across API keys, OAuth subscriptions and local endpoints

The provider list is unusually broad, and it is the reason the project is interesting for anyone who has a model contract they do not want to route through someone else's billing. For API keys, the README names OpenAI, Anthropic, Google, Azure, OpenRouter, Groq, xAI, Cerebras and Mistral among others. For OAuth, it names Anthropic covering Claude Pro and Max, and OpenAI Codex covering ChatGPT Plus and Pro. For a custom endpoint, it accepts OpenAI-compatible APIs and gives Ollama, vLLM and LMStudio as the examples. That last category is the one that changes what you can build, because a local model behind an OpenAI-compatible server means the add-in can run against a model on your own machine with nothing leaving the network. The configuration surface in Settings covers the provider, the model and the auth method, a CORS proxy, the thinking level, skills, and the web search and fetch providers with their API keys. The thinking level setting is worth a note, since exposing a reasoning budget to the user is something a few products do and most skip, and it lets a user trade latency against reasoning depth per task rather than per account.

A sandboxed shell and a virtual filesystem

The capability that distinguishes this from a plain chat sidebar is the pair of a sandboxed shell and a virtual filesystem. The VFS is a filesystem the agent operates on rather than the real disk of the machine, and the bridge CLI can browse it in a running session, listing the contents of a path inside a session's VFS. The SDK is where the VFS lives alongside storage, tools and skills. The design intent is fairly clear, and it is a good one. An agent that can read and write documents should not be given arbitrary filesystem or process access, because the moment it can, a prompt injection in a document becomes a command execution problem. A sandboxed shell and a separate virtual filesystem keep the blast radius inside the session and inside the document the user opened. The cost is that the agent cannot do everything a real shell could, so a workflow that genuinely needs a network fetch or a system tool has to go through a tool the SDK exposes rather than through a shell command. The README does not enumerate the shell's limits, so what the sandbox actually permits is something to read in the package documentation rather than assume.

Skills, and a settings panel to manage them

The skills system is a small feature with a large effect on how a chat assistant feels in a document editor. You install a skill from a single SKILL.md file, or from a folder that contains one, and you manage the installed skills from the Settings tab. The unit of installation being a markdown file is a deliberate simplification, since it means a skill is a document with instructions rather than a plugin with code, and it means the same install mechanism could carry a skill from one add-in to another. Given the shape of the repository, with a TODO.md at the top level and an AGENTS.md alongside, the skills are likely the extension point the author expects contributors to work on, since they are the part that can be added without touching the SDK, the bridge or the Office wrappers. The three add-in packages each carry a system prompt, so the default behaviour of the Word, Excel and PowerPoint agents differs, and a skill is layered on top of that. The SDK package listing includes skills among its responsibilities, which is a hint that the runtime treats them as a first class concept rather than as a bolt-on.

The bridge is the debugging story

The development section explains how a developer inspects a running add-in, and the tooling is the most interesting part of the repository for anyone building on it. During development the Office taskpane auto-connects to a local bridge server, and the bridge CLI can inspect the live add-in runtime, run tools and manage VFS files.

pnpm exec office-bridge list                         # List connected sessions
pnpm exec office-bridge inspect word                 # Inspect a session's tools & metadata
pnpm exec office-bridge tool word get_document_text  # Run a tool against the live add-in
pnpm exec office-bridge vfs ls word /home/user       # Browse the VFS

The exec command can run arbitrary JavaScript directly inside the Office taskpane, which the README calls useful for debugging and closing the agentic dev loop, and the examples show reading the active Word document body text and poking at taskpane globals and the DOM.

pnpm exec office-bridge exec word --code \
  "const body = context.document.body; body.load('text'); await context.sync(); return body.text;"

That last example is the mechanism to understand. The code runs inside the add-in, calls the Office.js body API, awaits a sync, and returns the text over the bridge, so you can call any tool or Office API from a terminal against a live session without reloading the add-in. For an agent system whose behaviour depends on what the model did to the document, being able to run a tool and see the result without a rebuild is the difference between a five minute and a five hour debugging cycle. The screenshot command, which captures a document page to a file, closes the loop on the visual side of the same problem.

Running it, and the honest production warning

The development commands are the quickest way to see any of this working, and the split between starting a dev server and launching Office with the add-in sideloaded is the pattern for Office add-in development generally.

pnpm dev-server:word        # Start Word dev server (https://localhost:3002)
pnpm start:word             # Launch Word with add-in sideloaded
pnpm build                  # Build all packages
pnpm typecheck              # TypeScript type checking (all packages)
pnpm lint                   # Run Biome linter

Each application gets its own port, with Excel on 3000, PowerPoint on 3001 and Word on 3002, and the bridge server on 4017, so all three can run at once. The check and validate targets are the pre-publication ones, with check combining typecheck and lint, and validate checking the Office manifests. The warning above the development section is the part to read before investing time, and it is unambiguous. The project is not production-ready and is not intended for publication to the Microsoft Add-in Store, and the author asks you to think of it as a framework and reference for building your own Office-based agents, while being happy to squash bugs reported in issues. The licence at the bottom of the README is MIT, and the top level of the repository adds a TODO.md, an AGENTS.md, a Biome configuration, a .hintrc, a pnpm workspace and an office-bridge directory alongside the packages. The recent releases show separate version lines for the word, sdk and ppt packages, all dated 2026-05-12, and the last push to the repository was on the same day.

Editorial conclusion

Adopt office-agents if you are building an Office add-in with an AI assistant and want the runtime, the tool layer, the virtual filesystem and the skills system already laid out, and you intend to publish the add-in yourself. Skip it if you want something you can ship to the Microsoft Add-in Store today, since the README says this project is not production-ready and not intended for publication there. Verify first which provider and auth method you will use, since the list spans API keys, OAuth subscriptions and custom OpenAI-compatible endpoints, and that your web search and fetch provider works through the configured CORS proxy.

Frequently asked questions

Official sources

1. hewliyang/office-agents on GitHub
2. Issues
3. README
4. Releases