DEV Community: Ilia Sokolov

Add Word-Editing Tools to a .NET IChatClient with OfficeAgent.NET

Ilia Sokolov — Sat, 01 Aug 2026 13:19:22 +0000

Most AI demos end with text in a chat window. Business workflows often need something more concrete: a Word document that a person can open, review, and approve.

If your .NET application already uses Microsoft.Extensions.AI.IChatClient, you do not need to adopt a full agent framework to add that capability. OfficeAgent.NET can expose bounded Word-editing operations directly as AIFunction tools.

The integration has a clear boundary:

IChatClient manages the conversation and function-calling loop.
OfficeAgent.NET inspects, plans, previews, and applies Word changes.
Your application controls document storage and delivery.

The document bytes stay outside the model context.

The workflow

The host performs five steps:

Register a document and receive an opaque document id.
Expose OfficeAgent.NET operations as AI functions.
Add those functions to the existing IChatClient.
Capture the output document id returned by apply_plan.
Retrieve the finished .docx through the configured document provider.

The complete sample makes one tracked edit: it changes 60 days to 30 days without modifying anything else.

1. Register the document and create the tools

Install the OfficeAgent.NET packages:

dotnet add package OfficeAgent.Core --version 0.2.1
dotnet add package OfficeAgent.Word --version 0.2.1
dotnet add package OfficeAgent.AgentFramework --version 0.2.1

Then configure Word support and register the source document:

using ServiceProvider services = new ServiceCollection()
    .AddWordFormat()
    .AddFileSystemDocumentProvider("contracts", storageRoot)
    .AddOfficeAgent()
    .BuildServiceProvider();

OfficeAgentClient office =
    services.GetRequiredService<OfficeAgentClient>();

DocumentReference source = await office.RegisterAsync(
    "contracts",
    Path.Combine(storageRoot, "contract.docx"));

AIFunction[] tools = new OfficeAgentTools(office).AsAIFunctions();

Despite the package name, this path does not use ChatClientAgent.
AsAIFunctions() returns ordinary functions that can be attached to an IChatClient.

2. Add function execution to IChatClient

Create the Azure OpenAI client, convert it to IChatClient, and add function invocation:

IChatClient chat = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deployment)
    .AsIChatClient()
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

UseFunctionInvocation() runs the tool calls requested by the model, returns their structured results, and continues until the model produces its final response.

In a production host, add a request-scoped function invoker that records tool calls and captures outputDocumentId from a successful apply_plan result. Do not rely on the model to repeat that id in its prose, and do not store request state in a shared singleton closure.

The runnable sample includes result normalization because function adapters can surface the same JSON result as either an object or a JSON string. Handling both forms makes output capture reliable.

3. Give the model a bounded editing request

Provide the registered document id, OfficeAgent guidance, and a narrow instruction:

var messages = new List<ChatMessage>
{
    new(
        ChatRole.System,
        $"""
        You are editing connectionId=contracts,
        documentId={source.ItemId}.

        {OfficeAgentTools.SystemPromptGuidance}

        Inspect before planning. Preview before applying.
        When applying, use saveMode NewVersion.
        """),
    new(
        ChatRole.User,
        "Change '60 days' to '30 days' as a tracked change. " +
        "Make no other edits.")
};

var options = new ChatOptions
{
    Tools = tools.Cast<AITool>().ToList(),
    AllowMultipleToolCalls = false,
    MaxOutputTokens = 1200
};

ChatResponse response =
    await chat.GetResponseAsync(messages, options);

The safety sequence is discovery, preview, then apply. OfficeAgent.NET validates the edit plan before changing the document, while the host retains control of which document is registered and where the result is stored.

4. Retrieve the edited Word document

After apply_plan commits successfully, retrieve the document using the output id captured by the host:

using var saved = await office.OpenReadAsync(
    DocumentReference.ForFileSystem(
        "contracts",
        outputDocumentId));

await using var output =
    File.Create("reviewed-contract.docx");

await saved.Stream.CopyToAsync(output);

The model never needs the .docx bytes. Your application can return the file through its normal download, attachment, SharePoint, or storage workflow.

Try the complete sample

The article excerpts focus on the integration boundary. The
complete runnable sample contains the full host, package references, Azure configuration, JSON result normalization, synthetic fixture, logging, and output checks.

Start with a synthetic document, keep the first run single-request, and confirm that the trace ends with apply_plan.

OfficeAgent.NET gives an existing .NET chat application a focused way to produce reviewable Word documents without moving file content through the model or replacing the application's current AI architecture.

How a Word-editing MCP server can reduce agent output tokens

Ilia Sokolov — Sat, 01 Aug 2026 12:49:46 +0000

Codex and Claude can edit Word documents without a dedicated document tool. They can open a .docx as a ZIP package, inspect its XML, write Python or C# to find the right node, change it, and save the package again.

That works, but the agent has to produce the editing toolset as well as the edit. Even a small request can turn into code for locating text across Word runs, preserving formatting, handling tracked changes, and keeping the document valid.

I wanted to know whether a Model Context Protocol (MCP) server that already implements that tools could reduce the output tokens an agent emits. I used OfficeAgent.NET, which exposes Word operations such as find, replace, format, comment, and accept revisions as tools. Instead of writing the XML manipulation, the agent can describe the change in a compact, structured tool call.

What I tested

Four agent and model combinations edited the same Word contract:

Claude Code with Sonnet 5;
Claude Code with Opus 4.8;
Codex with GPT 5.6 Sol;
Codex with GPT 5.6 Terra.

Each received the same seven editing tasks:

change text with tracked revisions;
format a paragraph;
fill a content control;
insert a sentence;
insert a table;
add a review comment;
accept all revisions.

The benchmark compared two paths:

Direct editing: the agent used the Open XML SDK or raw OOXML, with no document MCP.
MCP editing: the agent performed the edit through OfficeAgent.NET.

The primary comparisons ran five attempts per task and condition. A separate verifier, built directly on the Open XML SDK, checked the saved document. The token figures below use medians from verifier-successful attempts.

This benchmark covers edits to an existing document only. Creating a document from scratch is a different workload and is not included.

What happened

Across the seven tasks, the median task-level MCP/direct output-token ratios were:

Claude Code, Sonnet 5: 33%
Claude Code, Opus 4.8: 28%
Codex, GPT 5.6 Sol: 36%
Codex, GPT 5.6 Terra: 51%

Lower is better. A result of 33%, for example, means that the MCP workflow used about one third of the output tokens of direct editing for the median task-level comparison.

Every one of the 28 task and model comparisons had a lower successful-attempt median when the MCP path was used.

The reduction was not identical for every operation. Accepting revisions and adding comments benefited more than some simpler formatting and insertion tasks.

That supports the proposed mechanism: the more document-specific procedure the tool absorbs, the less implementation code the model has to generate.

Token savings and cost savings are not the same thing

The output-token reduction was large. The session-cost reduction was smaller.

For Claude, the median task-level session-cost ratio was:

83% of direct on Sonnet
84% of direct on Opus

Two of the fourteen Claude task and model comparisons cost slightly more with MCP, even though they used fewer output tokens.

A plausible contributor is input overhead. MCP tool definitions add context, while fresh input, cache reads, cache writes, and output tokens are priced differently. This benchmark did not isolate the contribution of each component.

The recorded figures are model-session costs, not total cost of ownership. They do not include the cost of hosting, securing, or maintaining the MCP server. Codex did not report comparable USD costs, so I did not make a cross-agent dollar comparison.

What this result does not prove

This was a pilot:

one Word document;
seven supported editing operations;
two agent environments;
two models per agent;
five attempts per primary comparison cell.

The direct baseline had the Open XML SDK available, but it did not have a mature reusable Word-editing abstraction. A team that already owns such an abstraction may see a smaller difference.

The verifier checked whether the requested OOXML change was present. It did not prove full visual equivalence or rule out every unintended change elsewhere in the document.

The result also does not mean that every MCP server will reduce tokens. The operation must be supported, and the agent must actually use the tool path.

Conclusion

In some Word-editing workflows, an MCP server can let agents emit fewer output tokens by moving document-specific implementation out of the conversation and into a reusable tool.

In this pilot, the median task-level MCP/direct ratio ranged from 28% to 51%, depending on the agent and model.

The practical lesson is not that MCP automatically makes agents cheaper. It is that a well-matched tool can remove a large amount of procedural work from the model.

For teams using AI agents to edit Word documents, that is worth testing against the operations they perform most often.

The project used in this benchmark is available on GitHub: OfficeAgent.NET

Letting a Copilot Studio Agent Edit Word Documents in SharePoint

Ilia Sokolov — Sat, 01 Aug 2026 12:37:50 +0000

Copilot Studio makes it easy to build custom AI agents. In very little time you can create, for example, an agent that drafts a standard customer contract from a few details. But it gets harder when the task is more than filling in blanks. Choosing different clauses for different clients, or editing an existing document instead of creating a new one, is not easy without additional tools. That's where OfficeAgent helps. As an MCP server, it gives agents tools to edit real Word documents, keeping their styling, comments, and tracked changes intact.

In the previous article I explained how to deploy the OfficeAgent MCP server to Azure. This article connects a Copilot Studio agent to it and lets it modify an existing Word document.

What you need before you start

1. The hosted MCP endpoint from the previous article. From that deployment you will need your tenant id and the Easy Auth app's client id.

2. A Copilot Studio agent - an existing one or a new blank agent.

3. An app registration for Copilot Studio to sign in with. Copilot Studio needs its own identity to obtain an Entra token to connect to the endpoint:

In the Entra admin center, open App registrations and create a new registration. Name it (e.g. officeagent-copilot), keep the defaults, and register it. Copy the Application (client) ID.
On the app's Certificates & secrets page, create a new client secret and copy its Value right away - it is shown only once.
You will add a redirect URL to this registration later - Copilot Studio shows it during the connection setup.

Add the MCP server to the agent

Open your agent in Copilot Studio and check that it uses generative orchestration (on the agent's Settings page, under Generative AI). MCP tools are not available under classic orchestration.
Open the Tools page, click Add a tool, and pick Model Context Protocol.
Enter a name (OfficeAgent), a short description ("edits Word documents in SharePoint through validated change plans"), and the server URL: https://<app-url>/, the root of the deployed container app.
For authentication, pick OAuth 2.0.

The OAuth values

All of these come from the deployment:

Field	Value
Client ID	the `officeagent-copilot` app's client id
Client secret	the secret you created for it
Authorization URL	`https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize`
Token URL	`https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`
Refresh URL	same as the token URL
Scopes	the scope the Easy Auth registration exposes, on its Expose an API page, typically `api://<easyauth-client-id>/user_impersonation`

Finish the connection

Finish the wizard. Copilot Studio now shows the redirect URL for this connection - copy it, go back to the officeagent-copilot registration in the Entra admin center, and add it under Authentication as a Web redirect URI.
Create the connection when Copilot Studio asks you to sign in. This is the moment the OAuth loop closes: you sign in, consent, and the tool shows as connected.

In the tool listing you should see seven tools: inspect_document,
find_in_document, preview_plan, apply_plan, register_document,
remove_document, and list_connections.

The first edit

With the tools added, you can ask the agent something concrete:

Update the payment terms in
https://contoso.sharepoint.com/sites/legal/Shared%20Documents/msa-draft.docx
from 30 to 45 days.

Under the hood, the agent will register the document with the OfficeAgent MCP server, find all appearances of "30 days", prepare a modification plan, and apply it.

The result lands in SharePoint as a new version of the document, and the edit itself is a Word tracked change - open the document and you review it like a colleague's edit, accept or reject. The agent proposes the change; you decide what the document finally says.

Whose permissions apply

In the deployment article's setup the server uses one application identity (appOnly), scoped with Sites.Selected to the sites you granted. Every user of the agent reaches the same documents, which fits back-office automation. The provider also supports an on-behalf-of mode, where the server acts as the signed-in user and SharePoint permissions apply per user - the right choice for an assistant many people share. The identity table in the deployment guide
covers what that mode requires.

Let me know in the comments if this article is useful, and a star on GitHub helps other developers find it.

Deploying the OfficeAgent.NET MCP Server to Azure

Ilia Sokolov — Sat, 01 Aug 2026 12:19:18 +0000

OfficeAgent.NET ships an MCP server that gives AI agents tools to edit real Word documents through typed, validated change plans. You can start it locally with a few commands:

dotnet tool install --global OfficeAgent.Mcp
officeagent-mcp --stdio

This is perfect if you want to use it with locally running agents such as Claude Code or Codex. But local is not always enough. Hosting becomes necessary in these cases:

Hosted agents. Copilot Studio and Microsoft 365 Copilot can only consume MCP over streamable HTTP at a public HTTPS endpoint.
Unattended automation. A document workflow that runs on schedule or on events needs the server running somewhere that isn't a laptop.
Shared server for a team. Instead of every user holding SharePoint credentials in a local config, one hosted instance holds them once, and clients get a URL.

This article shows how to deploy that endpoint to Azure Container Apps, connect it to your SharePoint document storage, and secure it with built-in authentication (Easy Auth).

What you need before you start

Before you start the deployment you need to prepare the following:

1. The container image. This article uses a prebuilt image available on the GitHub Container Registry:

ghcr.io/ilia-sokolov/officeagent-mcp:latest

Feel free to use it. If your policy requires your own registry, build the image from the Dockerfile in the repository, push it to your registry, and replace the reference - the steps are the same.

2. Your tenant id. In the
Entra admin center, it's on the Overview page.

3. An app registration for SharePoint access. OfficeAgent works through
providers: you define which document storage the agents may reach. It ships a filesystem provider and a SharePoint provider; for a hosted server,
SharePoint is the best option. The server needs its own identity to reach the documents:

In the Entra admin center, open App registrations and create a new registration. Name it (e.g. officeagent-sharepoint), keep the defaults, and register it. Copy the Application (client) ID.
On the app's Certificates & secrets page, create a new client secret. Copy its Value right away - it is shown only once.
Under API permissions, add a permission: pick Microsoft Graph, then Application permissions. Add Sites.Selected (least privilege - the app reaches only sites you explicitly grant) or Sites.ReadWrite.All (simpler, but every site in the tenant). Then grant admin consent.
If you chose Sites.Selected, grant the app Write access to the specific site or sites, for example with PnP PowerShell:

Grant-PnPAzureADAppSitePermission `
    -AppId "<app-client-id>" `
    -DisplayName "<app-name>" `
    -Site "<site-url>" `
    -Permissions Write

Deploy MCP in Azure portal

Create the app:

In the Azure portal, create a new Container App resource. Pick a resource group, name the app (e.g. officeagent-mcp), and let it create a new Container Apps environment.
On the Container tab: uncheck Use quickstart image. Name the container (e.g. officeagent-mcp), set Image source to Docker Hub or other registries, Image type to Public, set Registry login server to ghcr.io, and set Image and tag to ilia-sokolov/officeagent-mcp:latest.
The Environment variables grid is at the bottom of the same tab. Add the six variables from the table below.

These values configure the server's SharePoint connection:

Variable	Value
`OfficeAgent__SharePointConnections__0__ConnectionId`	`documents`
`OfficeAgent__SharePointConnections__0__AuthMode`	`appOnly`
`OfficeAgent__SharePointConnections__0__TenantId`	your tenant id
`OfficeAgent__SharePointConnections__0__ClientId`	the SharePoint app's client id
`OfficeAgent__SharePointConnections__0__ClientSecret`	the SharePoint app's client secret
`OfficeAgent__SharePointConnections__0__RegistrationIndexPath`	`/tmp/officeagent-index.json`

In this article we set up appOnly: the server acts as one application
identity for every caller. The provider also supports an on-behalf-of
flow, where the server acts as the signed-in user and SharePoint permissions
apply per user. See the
deployment guide
if you need that.

On the Ingress tab: enable ingress, accept traffic from anywhere, target port 8080.
Create the app. To verify, open https://<app-url>/healthz, where <app-url> is the URL of the created container app. It should return {"status":"ok",...}.

The endpoint is available now, but anyone can call it. Let's fix that by
enabling authentication.

Turn on Easy Auth:

In the created Container App, open the Authentication page (you'll find it under Security) and click Add identity provider. Pick Microsoft.
Let the form create the app registration for you. Leave App registration type on Create new app registration, give it a name (e.g. officeagent-easyauth). Under Additional checks, set Client application requirement to Allow requests from any application. The wizard creates the registration, the secret, and the wiring in one step.
Set Restrict access to Require authentication and Unauthenticated requests to HTTP 401 Unauthorized - this is an API, not a website; a login redirect would only confuse MCP clients.
Save. https://<app-url>/healthz now returns 401. The client must send an Entra bearer token for the Easy Auth app. You can check this using the following script:

TOKEN=$(az account get-access-token --resource api://<easyauth-client-id> --query accessToken -o tsv)
curl -H "Authorization: Bearer $TOKEN" https://<app-url>/healthz

What's next

Now you can use the MCP server with your client. In the next article I will
describe how to connect it to a Copilot Studio agent.

Let me know in the comments if this article is useful, and a star on GitHub
helps other developers find it.

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.