DOCSEARCHbyAlgolia
Submit Docs

Office Agents

repository·main·Indexed 19 days ago

https://github.com/hewliyang/office-agents

A framework and reference implementation for building AI-powered Microsoft Office Add-ins. It includes an agent runtime SDK, Svelte-based chat UIs via @office-agents/core, and a bridge server for local development and debugging. The ecosystem provides specialized packages for Excel and PowerPoint, featuring built-in tools for document manipulation, a Virtual File System (VFS), and a sandboxed shell with custom bash commands for file conversion and web interaction.

Tokens
76.1K
Snippets
250
Records
343
Agent score
67%

What's inside office-agents

  1. Overview of Office Agents packages

    main

    Office Agents is a monorepo of Microsoft Office Add-ins with integrated AI chat panels. It uses a Bring Your Own Key (BYOK) model for LLM providers and provides tools for reading/writing documents via a virtual filesystem (VFS) and a sandboxed shell.

    Core packages include:

    • @office-agents/sdk: Headless SDK containing the agent runtime, tools, storage, VFS, skills, OAuth, and web search.
    • @office-agents/core: Chat UI built with Svelte 5, re-exporting the SDK and providing chat components, settings, and sessions.
    • @office-agents/bridge: A local HTTPS/WebSocket RPC bridge and CLI for inspecting live Office add-in runtimes.
    • @office-agents/excel: Excel Add-in with spreadsheet tools and Office.js wrappers.
    • @office-agents/powerpoint: PowerPoint Add-in with slide/OOXML tools and Office.js wrappers.
    • @office-agents/word: Word Add-in with document text, structure, and OOXML tools and Office.js wrappers.
    | Package | Description |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [`@office-agents/sdk`](./packages/sdk) | Headless SDK — agent runtime, tools, storage, VFS, skills, OAuth, web search |
| [`@office-agents/core`](./packages/core) | Chat UI (Svelte 5) — re-exports SDK + chat components, settings, sessions |
| `@office-agents/bridge` | Local HTTPS/WebSocket RPC bridge + CLI for inspecting a live Office add-in runtime |
| `@office-agents/excel` | Excel Add-in — spreadsheet tools, Office.js wrappers, system prompt |
| `@office-agents/powerpoint` | PowerPoint Add-in — slide/OOXML tools, Office.js wrappers, system prompt |
| `@office-agents/word` | Word Add-in — document text/structure/OOXML tools, Office.js wrappers, system prompt |

  2. Use @office-agents/core for Chat UI

    main

    @office-agents/core provides the shared Svelte 5 chat UI layer for Office Agents. It re-exports the headless SDK and includes the generic chat interface used by the Excel, PowerPoint, and Word add-ins.

    Key UI components include:

    • ChatInterface: The main taskpane chat shell.
    • FilesPanel: For managing files.
    • ErrorBoundary: For handling runtime errors.
    • settings-panel.svelte: For managing providers, OAuth, web tools, and skills.
    • message-list.svelte: For rendering assistant and user messages.

  3. Implement the AppAdapter for Office integration

    main

    To integrate an Office-specific tool with the chat interface, you must pass an AppAdapter into the ChatInterface. The AppAdapter serves as the integration contract that allows the chat UI to communicate with the specific Office host application.

    An AppAdapter provides:

    • App-specific tools: Custom tools available to the agent.
    • System prompt construction: Logic to build the system prompt.
    • Document identity and metadata: Context about the active document.
    • UI Extensions: Optional Office-specific UI elements such as ToolExtras, HeaderExtras, and SelectionIndicator.
    • Link Interception: An optional handleLinkClick function to manage how links are opened within the Office environment.

  4. Start and stop the @office-agents/bridge server

    main

    The bridge is a local HTTPS/WebSocket server that allows external tools and CLIs to invoke Office.js operations inside Excel, PowerPoint, or Word.

    To start the server, use the root workspace scripts:

    pnpm bridge:serve

    To stop the server from another shell:

    pnpm bridge:stop
# or
office-bridge stop

    If the bridge is already running, attempting to start it again will report the existing healthy server instead of failing with EADDRINUSE.

    Default Server Endpoints:

    • HTTPS API: https://localhost:4017
    • WebSocket: wss://localhost:4017/ws

    Certificate Configuration: The bridge expects Office Add-in dev cert files at ~/.office-addin-dev-certs/localhost.crt and ~/.office-addin-dev-certs/localhost.key. You can override these locations using the following environment variables:

    • OFFICE_BRIDGE_CERT
    • OFFICE_BRIDGE_KEY
    pnpm bridge:serve
pnpm bridge:stop

  7. Install the @office-agents/word add-in

    main

    To install the Word add-in, first download the manifest.prod.xml file. Follow the specific steps for your operating system:

    Windows

    1. In Word, go to Insert → Add-ins → My Add-ins.
    2. Select Upload My Add-in.
    3. Choose the manifest.prod.xml file.
    4. Open the add-in from the ribbon.

    macOS

    1. Copy manifest.prod.xml to the following directory: ~/Library/Containers/com.microsoft.Word/Data/Documents/wef/
    2. Restart Microsoft Word.
    3. In Word, go to Insert → Add-ins → My Add-ins.
    4. Select the add-in.

    Word Web

    1. Open word.office.com.
    2. Go to Insert → Add-ins → More Add-ins.
    3. Select Upload My Add-in.
    4. Upload the manifest.prod.xml file.

  9. Development setup and commands

    main

    Use pnpm to manage the development lifecycle of the Office Agents monorepo.

    Dependency and Build Management:

    pnpm install                # Install all dependencies
pnpm build                  # Build all packages
pnpm typecheck              # TypeScript type checking (all packages)
pnpm lint                   # Run Biome linter
pnpm format                 # Format code with Biome
pnpm check                  # Typecheck + lint
pnpm validate               # Validate Office manifests

    Running Dev Servers and Launching Office:

    pnpm dev-server:excel       # Start Excel dev server (https://localhost:3000)
pnpm dev-server:ppt         # Start PowerPoint dev server (https://localhost:3001)
pnpm dev-server:word        # Start Word dev server (https://localhost:3002)
pnpm start:excel            # Launch Excel with add-in sideloaded
pnpm start:ppt              # Launch PowerPoint with add-in sideloaded
pnpm start:word             # Launch Word with add-in sideloaded
    pnpm install                # Install all dependencies
pnpm dev-server:excel       # Start Excel dev server (https://localhost:3000)
pnpm dev-server:ppt         # Start PowerPoint dev server (https://localhost:3001)
pnpm dev-server:word        # Start Word dev server (https://localhost:3002)
pnpm start:excel            # Launch Excel with add-in sideloaded
pnpm start:ppt              # Launch PowerPoint with add-in sideloaded
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
pnpm format                 # Format code with Biome
pnpm check                  # Typecheck + lint
pnpm validate               # Validate Office manifests

  10. Initialize the AgentRuntime

    main

    To run an agent, you must coordinate an AgentRuntime, a RuntimeAdapter, and an AgentContext.

    1. AgentContext: Manages the virtual filesystem (VFS), bash shell, and file operations. Use new AgentContext(opts?) to initialize it with optional namespace, staticFiles, skillFiles, or customCommands.
    2. RuntimeAdapter: Defines the agent's capabilities, including tools, staticFiles, and how to build the system prompt.
    3. AgentRuntime: The main orchestrator. Create it with new AgentRuntime(adapter, context) and call .init() to load configurations, restore sessions, and initialize the VFS.
    const context = new AgentContext({ namespace: 'my-app' });
const adapter = new MyRuntimeAdapter(); // Implements RuntimeAdapter
const runtime = new AgentRuntime(adapter, context);
await runtime.init();

// Send a message
const response = await runtime.sendMessage("Hello agent!");

  12. Integrate the bridge client into an Office Add-in

    main

    To enable bridge connectivity within your application, import startOfficeBridge() from @office-agents/bridge/client and pass the current AppAdapter.

    Connection Configuration:

    • The client enables automatically on localhost by default.
    • Query Parameter: ?office_bridge=1 to enable.
    • WebSocket URL Override: Use query parameter ?office_bridge_url=wss://localhost:4017/ws.
    • LocalStorage Overrides:
      • office-agents-bridge-enabled: To force enable.
      • office-agents-bridge-url: To specify a custom bridge URL.