Safe Partial Content Editing by LLM Agents

This is a specific problem within the broader domain of architectural issues of modern LLM agents.

The Problem

In a standard CRUD approach, a large text field like content is updated as a whole. For a classic deterministic client, this is often acceptable. For an LLM agent, such a model is riskier: if the task is to modify a single line, link, paragraph, or section, the agent is still forced to retrieve the document, reproduce it in its entirety, and send a new full version.

Because of this, a small edit receives too large a blast radius. Unnecessary tokens and operations arise, along with the risk of accidentally modifying neighboring text, losing part of the document, overwriting a newer version, or making unintended changes.

This problem manifested in practice while working with Concepts fi1osof.ru: to fix a single internal link, the agent had to re-transmit the entire content. For a system where AI agents must regularly create and maintain large articles, Concepts, tasks, and other content, this editing method does not scale well.

What Already Exists in Engineering Practice

The idea of partially modifying a resource appeared long before LLMs. RFC 5789 — PATCH Method for HTTP introduces PATCH precisely because PUT implies a complete replacement of a resource's representation, whereas many applications need to modify only a part of it.

For structured JSON data, RFC 6902 — JSON Patch describes a sequence of operations: add, remove, replace, move, copy, test. This is an important precedent: the client passes not a new state as a whole, but a set of changes against the existing state.

Modern coding agents use a similar approach specifically for LLMs. The OpenAI tool Apply Patch allows the model to modify files via structured diff operations instead of returning the full file contents. The GitHub Copilot coding agent also builds its workflow around changes in a separate branch and review of the resulting diff: official GitHub documentation.

At the tool-protocol level, the Model Context Protocol treats tools as operations affecting external systems: MCP Tools specification. In the evolution of MCP, a tool risk vocabulary is formalized separately—readOnly, destructive, idempotent, and other characteristics: Tool Annotations as Risk Vocabulary. This does not solve the partial editing task directly, but confirms the general shift from "the model has a function" to a more rigorous description of operation consequences.

At the same time, there is no ready-made, universally accepted standard for safe editing of arbitrary CMS/MDX documents by LLM agents yet. Coding-agent patch mechanisms solve a similar problem for files, and HTTP/JSON Patch for classic APIs, but agent-native content editing remains a separate engineering challenge.

Requirements for a Future Solution

For haih-agent, a mechanism is needed where an agent can modify the minimally necessary part of a document without being forced to regenerate the entire content.

Desired properties:

• changes must be local and scoped;
• the server must verify that the agent is editing the version of the document it actually saw;
• ambiguous operations must not be applied silently;
• multiple changes should ideally be applied atomically;
• after modification, the document must undergo re-validation of MDX/Markdown;
• full replacement of content must remain available for cases where a complete rewrite of the material is genuinely required;
• the mechanism should be suitable not only for Concepts, but also for Tasks, Projects, and other entities with large text fields.

Option 1. Partial Editing via Text Matching

The most context-efficient option is for the agent to read standard Markdown/MDX and send commands containing the expected source fragment and its replacement.

Conceptually:

replace:
  match: "exact existing fragment"
  with: "new Markdown/MDX"
  expectedMatches: 1

The mechanism can support several universal operations: replacement, deletion, insertion before or after a found fragment. These are not separate methods for links, words, or sentences, but a general language of local text changes.

Pros

• minimal context growth: the agent continues reading compact source MDX;
• easy to explain to both the model and a human;
• well suited for small and medium local changes;
• the server can safely reject the operation if match is not found or is ambiguous;
• relatively low complexity for the initial implementation.

Cons

• exact matching is sensitive to text changes that have already occurred;
• the agent sometimes has to transmit a fairly large unique context fragment;
• structural operations like "add an item specifically to this list" are expressed less naturally;
• text matching knows less about the semantics of the MDX document.

Option 2. Reading and Addressing via MDX AST

MDX already has a structural representation via the unified/remark ecosystem. remark-mdx allows parsing MDX into a syntax tree. The base unist format contains position.start and position.end for nodes; points can include offset, meaning a node can be tied to an exact range in the source file: unist specification.

In such a model, the agent reads a Concept not just as text, but as a tree: heading, paragraph, link, listItem, MDX JSX element, etc. It can then address a specific node or range and send new Markdown/MDX only for the modified part.

Importantly, it is not necessary to serialize the entire AST back afterwards. Positions can be used to modify the corresponding range of the source code, keeping the rest of the document byte-for-byte intact.

Pros

• the agent sees the actual document structure, not just a sequence of characters;
• it is easier to safely distinguish headings, links, lists, MDX components, and other nodes;
• structural changes can be more precise and natural;
• potentially provides a strong foundation for future agent-native content operations.

Cons

• the AST is significantly larger than the source Markdown/MDX and can cause an explosive growth in transmitted context and cost;
• one must decide how stably to address nodes between reading and writing;
• offsets become invalid after concurrent document modification;
• the command interface for the agent becomes more complex;
• a full AST for large articles may be unjustifiably expensive if only a single line needs to be changed.

Possible Combination

The two approaches are not necessarily mutually exclusive.

The base mode can use compact source MDX + text matching for most edits. AST can be brought in on demand: for a complex structural change, the agent requests the tree only for the required section or document, and then performs an address-based operation.

Such a hybrid potentially preserves Markdown's main advantage—context compactness—while retaining a structural mode for cases where plain-text patches are too fragile.

Protection Against Outdated Versions

Regardless of the chosen addressing method, version control is required. RFC 5789 specifically highlights the risk of PATCH collisions and the use of conditional requests/ETags to prevent applying changes to an unexpected resource state.

For haih-agent, the equivalent can be a revision/hash/updatedAt: the agent receives the version along with the document, and the patch is applied only if it has not changed. Otherwise, the operation is rejected, and the agent re-reads the current context.

Current Status

This is an exploration of architectural issues, not a description of an implemented feature.

Implementation of partial/agent-safe editing in haih-agent has not yet begun. Currently, requirements, existing industry practices, and two main options for our own solution are being defined: compact editing via text matching and structural editing via MDX AST.

Returning to implementation is definitely planned: given the current direction of development for fi1osof.ru and other sites, AI agents will work extensively with large volumes of content. Complete rewriting of a massive article just to change individual lines, paragraphs, or blocks creates unjustified costs and the risk of data loss. Therefore, safe partial editing is becoming not a convenience, but a necessary infrastructure layer for an agent-managed CMS.