Doco

What an AI Agent Actually Does Inside Doco

What an AI Agent Actually Does Inside Doco

A reliable knowledge agent should establish scope, locate evidence, make the smallest justified change, and verify the authoritative result instead of downloading and rewriting everything.

Doco series · Article 5

What does that agent actually do after you connect it to a knowledge base?

In Doco, the core loop can be summarized in six verbs:

browse → search → read → traverse → edit → watch

That sequence matters. It replaces the tempting but unsafe pattern of “download everything, guess the target, rewrite the file, and say done.”

The MCP tools specification treats tools as model-controlled actions and recommends keeping a human able to deny invocations. Doco's loop adds evidence and version checks inside that action boundary.

A concrete task

Suppose the user asks:

Change the production release window from 20:00 to 20:30, and confirm that the rollback plan is still valid.

This is not a search-and-replace operation. A defensible agent needs to locate the right environment, establish evidence, understand dependencies, make a narrow change, and verify the resulting state.

1. Browse: establish where you are

The agent first checks its identity and scopes, then enumerates knowledge bases and folders. It determines:

  • whether it is connected to local, staging, or production;

  • whether its token is read-only or read-write;

  • the real IDs of the target knowledge base and document;

  • the document's place in the hierarchy.

This prevents mundane but costly mistakes: guessing IDs from memory, writing to the wrong workspace, or creating a duplicate because a document already existed elsewhere.

2. Search: locate the current fact

The agent searches for “production release window” and asks for complete enumeration. A useful hit includes the document URI, block ID, folder path, heading path, nearby context, source version, index version, and query completeness.

If complete=false, the agent cannot conclude that the knowledge base lacks the answer. It must fall back to additional reading or report that search coverage is incomplete.

3. Read: spend context around evidence

The agent inspects the outline, then reads around the hit:

Release window
  Pre-flight checks
  Production releases run Wednesday at 20:00.  <- target block
  Notify the on-call engineer in advance.

Incident response
  Use blue-green rollback after a failed release.

The surrounding blocks expose constraints without consuming the entire runbook. A continuation cursor lets the agent request more when needed without silently stitching together content from different document versions.

4. Traverse: check what the change affects

“Is the rollback plan still valid?” cannot be answered from the target sentence alone. The agent follows the depends_on relationship to the rollback runbook and checks whether:

  • the relationship is valid;

  • the evidence is current;

  • the target still exists;

  • the source version matches the current document.

Stale or dangling evidence becomes uncertainty in the report, not a confident conclusion. Traversal is not a substitute for reading the source; it is a way to find the next evidence that must be inspected.

5. Edit: patch only the target block

The agent reads the current block and version, then changes only the sentence:

Production releases run Wednesday at 20:30.

The write carries If-Match. If another edit occurred after the read, Doco returns 409 and the agent must re-read before making a new decision. RFC 9110 section 13.1.1 describes this use of If-Match to prevent accidental overwrites, also known as the lost update problem.

After a successful write, the agent reads the authoritative document again. An HTTP 200 is not enough; the target must contain the new value and adjacent blocks must remain intact.

6. Watch: verify the knowledge world catches up

Using a saved changes baseline, the agent checks which blocks were added, removed, moved, or modified. It then verifies that:

  • search can find the new time;

  • the indexed version matches the source version;

  • summaries are current or explicitly stale;

  • related evidence remains valid.

If the change history was compacted, sync_required=true tells the agent to perform a full synchronization instead of pretending that an incomplete delta is complete.

Three interfaces, one model

Agents can enter through MCP, CLI, or the REST API. They share the same documents, block IDs, versions, permissions, and errors. MCP makes tools discoverable to clients such as Claude Code and Cursor. CLI is convenient for terminals and scripts. REST is the integration foundation.

A read-only agent can still browse, search, inspect outlines, follow relationships, and watch changes. Starting with read-only access is often the best way to prove answer quality before granting writes.

“Done” is an evidence report

A useful completion message resembles:

Document: Production release guide
Target: doco://doc/...#block=block_...
Version before: sha256:...
Version after: sha256:...
Authoritative read-back: passed
Search projection: current, complete=true
Relationship evidence: valid, current
Conflict: none

It is not glamorous. It tells the user what changed, what was checked, and which uncertainty remains.

Honest boundaries and disclosure

I build Doco, so this is a first-party description of the workflow the product is designed to support. Doco currently uses structured full-text search rather than an all-knowing semantic search. A 409 prevents a stale write from silently winning, but it does not understand or merge competing intentions. Relationships, summaries, and search results are derived projections that may become stale and must report that state. Human collaboration cursors are visible today; a transient cursor for an API-connected agent's pending block edit remains future work.

FAQ

Does an agent need write access to use Doco?

No. A read-only token can browse the hierarchy, search, read around evidence, follow relationships, and watch for changes. Grant write scope only when the workflow actually requires maintenance.

Why not let the agent rewrite the whole document?

A whole-document rewrite expands the blast radius and makes concurrent changes harder to preserve. A stable block target plus a version check keeps the intended change narrow and forces a reread when the source has moved.

Does a successful API response prove the task is finished?

No. The agent should read back the authoritative document and verify related projections. Success means the intended source state is visible and the remaining uncertainty is reported, not merely that a request returned 200.

Bottom line

A reliable agent in Doco discovers the real workspace, finds evidence, reads narrowly, follows dependencies, patches one stable block under a version check, and validates both the source and its derived projections. The workflow is deliberately conservative: discover first, gather evidence, change only the target, read it back, then verify that the surrounding knowledge is still fresh.