DEV Community: Ilia Sokolov

Edit SharePoint Word Documents from Any AI Agent over MCP with OfficeAgent.NET 0.2

Ilia Sokolov — Mon, 29 Jun 2026 11:17:11 +0000

A few weeks ago I released OfficeAgent.NET 0.1, an open-source .NET library that lets AI agents create and edit real Word documents. Instead of manipulating the Open XML themselves, they describe their intent as a typed, validated change plan, and the library turns it into the Open XML that carries it out: tracked changes, tables, comments, and content controls included. Version 0.1 shipped with an integration for Microsoft Agent Framework (MAF), so you could give those document tools to a custom .NET agent.

Today I'm introducing version 0.2. It exposes the same workflow over the Model Context Protocol (MCP), so any MCP-capable agent can read and edit real Word documents. This version also adds a SharePoint document provider, so agents can work on documents where they are actually stored: directly in SharePoint, one of the most widely used cloud document stores in the enterprise, rather than on a local disk.

Any agent, over MCP

MCP is an open standard for how an AI agent discovers and calls tools. OfficeAgent.NET 0.2 ships OfficeAgent.Mcp, a server (built on the official C# MCP SDK) that projects the document workflow as MCP tools:

inspect_document - a structured map of the document: outline, paragraphs with stable ids, styles, content controls, tables, images, and revisions.
find_in_document - text search that returns content-verified anchors to target.
preview_plan - a dry run of a change plan; nothing is written, the agent gets a before/after report and any validation errors.
apply_plan - the all-or-nothing commit, saved through the configured storage.
register_document / remove_document / list_connections - point the agent at a document to work on, release it afterwards, and discover the connections the host configured.

Copilot Studio, Microsoft 365 Copilot, Claude and Claude Code, OpenAI's Codex, and VS Code support MCP and can use this server.

The server runs in two hosting modes: stdio, used by locally running agents such as Claude Code and Codex, and an ASP.NET Core app over streamable HTTP, required by hosted agents such as Copilot Studio and Microsoft 365 Copilot.

Working on documents in SharePoint

OfficeAgent works through document providers. An agent registers a document with a provider and gets back an opaque id, which it then uses to address that document in every operation. 0.2 adds a SharePoint provider alongside the filesystem provider from the initial release.

The SharePoint provider reads and writes documents directly in SharePoint - the system most organizations in the Microsoft ecosystem use to store their documents. A document is registered by its URL or its Graph driveId/itemId pair; from there the agent runs the same inspect → preview → apply loop it would run against a local folder.

Two things make it safe to point an agent at a real document:

You review every change. The agent's edits arrive as Word tracked changes - accept or reject them like a colleague's. And each change is verified against the live document, so it edits the exact place you meant or fails safely, instead of silently rewriting the wrong clause.
It's scoped to you. Acting on behalf of the signed-in user (OAuth 2.0 On-Behalf-Of), the agent can only open and edit what you're already allowed to in SharePoint - not a shared account with broader reach.

Try it yourself

# the MCP server
dotnet tool install --global OfficeAgent.Mcp --prerelease

# the SharePoint provider
dotnet add package OfficeAgent.SharePoint --prerelease

# the core library
dotnet add package OfficeAgent.Core --prerelease

Source, samples, and the full hosting and client-setup guides are on GitHub: https://github.com/ilia-sokolov/OfficeAgent.NET

Version 0.2 of OfficeAgent.NET opens the document workflow to more agents and more enterprise use cases. Copilot Studio agents, Microsoft 365 Copilot, Claude Code, and Codex can now create or modify Word documents from user intent - without touching OOXML directly, without losing details, and without leaving the user to fix the document afterwards. And with the new SharePoint provider, agents can do it right where most of the documents already live.

Try it out and tell me what you think - that feedback will shape 0.3. If the direction is useful to you, add a star on GitHub to help other developers find it.

Word Document Editing for AI Agents - Introducing OfficeAgent.NET 0.1

Ilia Sokolov — Thu, 11 Jun 2026 18:02:29 +0000

A few weeks ago I wrote about why AI agents struggle with Word documents. The short version: agents produce text, Markdown, JSON, and HTML, but a .docx is an OOXML package, and most of what makes it a Word document lives in XML parts outside the visible text. Something has to translate the agent's output into a valid Word file, and the Word file back into something the agent can reason about. I called this the agent-document layer, and announced an open-source project to build it for .NET.

Today the first version is available. OfficeAgent.NET 0.1 is an open-source (MIT) .NET library that lets an AI agent describe Word document changes as a typed plan, while the library handles the Open XML details.

If your agents generate proposals, contracts, reports, or review packs, this layer is the missing piece of document automation between the model and the final .docx. This article is a first look at what the release contains and how it works.

The core idea: the agent never writes document bytes

The design decision behind OfficeAgent.NET is simple: the language model never produces .docx content directly.

Instead, the agent expresses intent as a plan: a typed, JSON-serializable list of operations. Replace this clause as a tracked change. Fill that content control. Add a row to this table. Attach a comment to that paragraph. JSON works well here because models produce it reliably and .NET code can validate it strictly. The library translates the plan into the Open XML manipulations that carry it out.

Version 0.1 ships 15 operations for text, table, image, and styling manipulations, for comments and document properties, and for accepting or rejecting existing tracked revisions.

The workflow: inspect → find → preview → commit

Every edit follows the same four steps:

Inspect - the agent gets a structured map of the document: the outline, paragraphs with stable ids, styles, content controls, tables, images, and revisions.
Find - the agent searches for text and gets an address back for each match.
Preview - the plan is checked against the current document. Nothing is written; the caller gets a before/after report and any validation errors.
Commit - the plan is applied as one all-or-nothing transaction. If any step fails, nothing is written.

The addresses are called anchors, and they are the safety mechanism. The library issues anchors from inspect and find; the agent reuses them and never invents one. Each anchor carries the content it expects to find, and at commit time the library re-checks it against the live document. If the document changed in the meantime, the operation fails safely instead of editing the wrong place.

Document providers: filesystem now, SharePoint and more later

OfficeAgent.NET does not read and write files directly. Documents come from document providers, an abstraction that lets the library work with any file source. The application registers a document with a provider (for the filesystem provider, by its path) and receives an opaque document id in return. From that point on, inspect, find, preview, and commit all address the document by that id, and the provider takes care of loading from and saving to the underlying store.

Version 0.1 ships a filesystem provider. Other providers, such as SharePoint, a database, or any custom store, can implement the same interface, and more will become available in later versions.

Editing Word documents from a Microsoft Agent Framework agent

The main scenario for OfficeAgent.NET is an agent doing the editing itself. For that, the workflow is exposed as agent tools over Microsoft.Extensions.AI: inspect_document, find_in_document, preview_plan, and apply_plan. Wiring them into a Microsoft Agent Framework agent looks like this:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;
using OfficeAgent.AgentFramework;
using OfficeAgent.Core;
using OfficeAgent.Core.DocumentProviders;
using OfficeAgent.Word;

var services = new ServiceCollection()
    .AddWordFormat()
    .AddFileSystemDocumentProvider("workspace", "/srv/officeagent/workspace")
    .AddOfficeAgent()
    .BuildServiceProvider();

var client = services.GetRequiredService<OfficeAgentClient>();

// Register the document with the provider; get an opaque id back.
var doc = await client.RegisterAsync(
    "workspace", "/srv/officeagent/workspace/contract.docx");

var tools  = new OfficeAgentTools(client).AsAIFunctions();
var prompt = "You are editing documentId=" +
           doc.ItemId +
           " on connectionId=workspace.\n\n"
           + OfficeAgentTools.SystemPromptGuidance;

AIAgent agent = new ChatClientAgent(
    chatClient, // any Microsoft.Extensions.AI IChatClient
    instructions: prompt,
    name:         "OfficeAgent",
    description:  "Edits Word documents using OfficeAgent.NET.",
    tools:        tools.Cast<AITool>().ToList(),
    services:     services);

From here the agent drives the document itself: it inspects, finds anchors, builds a plan, previews it, and applies it through the tools. OfficeAgentTools.SystemPromptGuidance provides ready-made instructions that teach the model the inspect → plan → apply protocol. apply_plan saves the result and returns an output document id rather than sending .docx bytes back through the model; the host reads the result from storage and delivers the file through its own download or attachment API. A runnable Azure OpenAI example is in the samples/AgentEdit project.

Using OfficeAgent.NET as a .NET library

The same workflow can also be driven directly from C# code, without a model in the loop:

// service registration and document setup are the same
//as in the agent example

var client = services.GetRequiredService<OfficeAgentClient>();
var doc = await client.RegisterAsync(
    "workspace", "/srv/officeagent/workspace/contract.docx");

// inspect → find → preview → commit, addressing the document by its id
var inspect = await client.InspectAsync("workspace", doc.ItemId);
var hit     = (await client.FindAsync(
    "workspace", doc.ItemId, new FindQuery("Acme Corp"))).First();

var plan = new DocumentPlan
{
    Snapshot   = inspect.Snapshot,          // opt in to drift detection
    Operations = new PlanOperation[]
    {
        new ChangeTextOp
        {
            Target = hit.Anchor,
            With = "Globex Inc.",
            Mode = ChangeMode.Tracked
        }
    }
};

var preview = await client.PreviewAsync("workspace", doc.ItemId, plan);
if (!preview.IsValid) { /* surface preview.Errors */ return; }

var result = await client.CommitAsync("workspace", doc.ItemId, plan);
if (result.Committed)
{
    using var saved = await client.OpenReadAsync(result.Document);
    // saved.Stream holds the edited bytes;
    //result.Document.ItemId is the new id.
}

The tracked edit lands as a real Word revision, with insert and delete runs that show up in Word's review pane, not as flattened text. The samples/QuickEdit project in the repository contains a runnable version of this flow.

What 0.1 covers, and what it doesn't yet

Version 0.1 covers Word .docx documents and the full editing workflow: inspect, find, preview, and transactional commit, protected by content-verified anchors and optional snapshot-based drift detection. The release includes the 15 operations described above, the filesystem document provider together with the interface other file sources can implement, the agent tools for Microsoft Agent Framework, two runnable samples (QuickEdit and AgentEdit), and a documentation set.

This is a 0.1 preview release. Expect rough edges, and expect some APIs to change based on feedback.

Try it, and tell me where it breaks

dotnet add package OfficeAgent.Core --prerelease
dotnet add package OfficeAgent.Word --prerelease

# for the agent-tools path
dotnet add package OfficeAgent.AgentFramework --prerelease

The source, samples, and documentation are on GitHub: https://github.com/ilia-sokolov/OfficeAgent.NET

This is early work, but the direction is clear: make real Word documents usable from agent workflows without requiring every agent developer to become an OOXML expert. If your agents need to produce real Office documents and this is (or isn't) the shape you would want, open an issue and tell me what's missing. That feedback is the whole point of shipping this early. And if the direction is useful to you, a star on GitHub helps other agent developers find it.

Why AI agents struggle with Word documents, and what to do about it

Ilia Sokolov — Fri, 22 May 2026 19:07:06 +0000

For a lot of professionals in consulting, finance, sales, HR, legal, and operations, the final product is a document: a proposal, contract, report, invoice, brief, or review pack. Nowadays AI agents help people produce these documents. Agents draft individual sections or entire documents. They produce text, Markdown, JSON, and HTML as part of document-production workflows, and they can create basic .docx files from scratch. But if you ask them to modify an existing document, or to produce a new one that follows an example template - the result usually disappoints. The produced documents frequently contain one or more of these problems:

Fonts, colors, paragraph spacing, header and footer elements silently disappear.
Headings get replaced with formatted text.
Numbered lists turn into literal numbers.
Tables get flattened or lose formatting.
Tracked changes and comments vanish from the output.
Content controls are replaced with text instead of populating them.

Why Word documents are hard for agents

A .docx is not a text file. It's an OOXML package: a zipped set of XML files containing all document elements and metadata. Most of what makes a Word document a Word document lives in those side files, not in the visible text.

Agents produce plain text, Markdown, JSON, and HTML - not formats that preserve Word's document semantics by themselves. Even when an agent uses a Word-specific library to process documents, it usually works with the visible content and misses structure and styling parts that live outside the text, so styles, numbering, tracked changes, and comments get dropped.

The missing translation layer

Something has to translate the agent's output into a valid Word file - and translate the Word file back into something the agent can reason about. Call this the agent-document layer.

In one direction, the layer describes the document to the agent in agent-native terms: sections, paragraphs, headings, tables, content controls, comments, and review locations. The agent sees a document model it can reason about.

In the other direction, the agent responds with a typed change plan. JSON works well for this: it's structured, explicit, easy for models to produce, and easy for .NET code to validate. The agent says what it wants (e.g. insert this clause as a tracked change, attach this comment to that paragraph, add this row to that table) and the layer applies the plan to the .docx.

The Open XML manipulations are managed by the layer, not by the agent or the application developer.

The .NET landscape today

If you operate in the .NET landscape, several categories of tools are available for working with Word documents:

Raw OOXML control. Tools like Microsoft Open XML SDK give full access to the .docx internals, but developers still have to manage Word structure manually.
Rich-text conversion. HTML or Markdown-to-Word pipelines are useful for simple generation, but often fail to preserve numbering, comments, tracked changes, and review structure.
Template filling. Placeholder tools work well for fixed templates, but are too limited for clauses, tables, redlines, or comments.
Word object models. Libraries like DocX, OfficeIMO, and NPOI make Word editing easier, but the application still decides every structural change.
Full document platforms. Aspose.Words, GemBox.Document, and TX Text Control provide broad document automation, but they are not designed to act as a contract between an AI agent and a Word file.

All these tools can be building blocks for the agent-document layer, but none of them are the layer itself. They don't let an agent express document intent and receive back a valid, reviewable .docx that preserves the user's template or sample document.

Introducing OfficeAgent.NET

I'm starting OfficeAgent.NET to build this layer for .NET: https://github.com/ilia-sokolov/OfficeAgent.NET.

The goal is to give AI agents and .NET applications a simple way to describe Word document changes in structured terms, then let the library handle the OOXML details. The first focus is Word: opening existing .docx templates, filling content controls, inserting structured tables, producing tracked-change suggestions, adding comments, and saving documents that preserve the user's template.

This is early work, but the direction is clear: make real Word documents usable from agent workflows without requiring every agent developer to become an OOXML expert.