A context repository is only as good as it is current. Agents are often the first to notice a document is wrong: the runbook step that no longer works, the question nobody has written up. This recipe lets them fix it, safely.
Three rules make agent edits safe:
- Change a part, not the whole. Use
editsto change one section or sentence. People editing other parts of the document in the app keep their work. - Send the version you read. With
base_version, a change based on an old copy fails with409 version_conflictinstead of quietly undoing someone's edit. - Leave a trail. Every change is a new version under the key owner's name, and reviewers are asked to review the document again when its body changes. Use a key made for the agent, so its changes are easy to tell apart.
Agents that write need knowledge:write. Make a Custom key with Playbooks and documents set to Read and change and nothing else, so the agent can't touch projects, tasks or anything outside your playbooks. Name it after the agent, and over MCP limit the agent to the document tools it needs (enabled_tools in Codex, the toolset configs with Claude, allowed_tools with OpenAI).
Fix a step in place
The agent followed a runbook, found a step was wrong, and knows the fix. Over REST, read the document, send a targeted edit with its version, and on a conflict read it again and retry:
import os
import time
import uuid
import httpx
api = httpx.Client(
base_url="https://developers.playbookops.ai/v1",
headers={"Authorization": f"Bearer {os.environ['PLAYBOOKOPS_API_KEY']}"},
timeout=60,
)
def edit_document(document_id: str, edits: list[dict], attempts: int = 3) -> dict:
"""Apply edits to the latest version, re-reading if someone else saved first."""
for _ in range(attempts):
doc = api.get(f"/documents/{document_id}").json()
res = api.patch(
f"/documents/{document_id}",
json={"base_version": doc["version"], "edits": edits},
headers={"Idempotency-Key": str(uuid.uuid4())},
)
if res.status_code == 409 and res.json()["error"]["code"] == "version_conflict":
time.sleep(1)
continue # someone saved in between: read again and retry
if res.is_error:
raise RuntimeError(res.json()["error"]["message"])
return res.json()
raise RuntimeError("The document kept changing; try again later")
edit_document(
"DOCUMENT_ID",
[
{
"op": "replace_text",
"find": "Run `fly deploy` from your laptop.",
"replace": "Run the **Deploy** workflow in GitHub Actions. Deploying from a laptop is no longer allowed.",
}
],
)
Edits find their place by text and headings, so retrying them on a newer version usually just works. If an edit no longer applies, because someone already fixed the step, you get 400 edit_failed saying why, and nothing changes. That's the right outcome. See edits for every kind of change.
Log what was learned
Some documents grow by adding to them: a known-issues list, an FAQ, a decisions log. An append to a section is safe without base_version, because it doesn't depend on what else the document says:
api.patch(
"/documents/DOCUMENT_ID",
json={
"edits": [
{
"op": "append",
"section": "Known issues",
"markdown": "- **Health check timeouts after deploy** (Nov 21): the worker needs 90 seconds to warm up. "
"Wait before rolling back. Found by the on-call agent; "
"[@Ana Ruiz](mention://user/PERSON_ID) to confirm.",
}
]
},
headers={"Idempotency-Key": str(uuid.uuid4())},
)
Mentioning the document's owner notifies them, so a person checks what the agent added.
Draft, don't publish
For anything new, have the agent write a draft and let a person decide. Documents are created as drafts unless you say otherwise:
playbook_id = "PLAYBOOK_ID"
api.post(
f"/playbooks/{playbook_id}/documents",
json={
"title": "Rotating the Stripe webhook secret",
"document_type": "procedure",
"tags": ["agent-draft"],
"content": "Written by the on-call agent after the Nov 21 incident. "
"[@Ana Ruiz](mention://user/PERSON_ID) please review.\n\n## Steps\n\n1. …",
},
headers={"Idempotency-Key": str(uuid.uuid4())},
)
The agent-draft tag makes the agent's drafts easy to find and review together.
Over MCP
Agents connected over MCP have the same tools: read_document, update_document and create_document. Tell them how to use them:
When you find that a PlaybookOps document is wrong or missing something:
- Read it with read_document first, and note its version.
- Change only what's wrong, with update_document edits (replace_text or
replace_section) and base_version set to the version you read. Never send
content to replace the whole document.
- If you get version_conflict, read the document again and redo your edit on
the new version.
- For something new, create a draft with create_document, tagged agent-draft,
and mention the playbook's owner so they review it.
- Send an idempotency_key (any new UUID) with every change, and send the same
one if you retry that change after a timeout or error.
- Tell me what you changed, with a link to the document.
Most clients ask before running a tool that changes something; keep that on for document changes until you trust the agent. In Codex, default_tools_approval_mode = "writes" does this for you.
The idempotency_key matters most for appends and new documents: base_version already stops an edit from applying twice, but nothing else stops a retried append. See retries over MCP.
Next
- Documents covers every field and edit.
- Answer with citations finds the gaps worth writing up.