Multi-Agent Operations

Why multi-agent strategy is necessary

When multiple workers can touch the same documents, correctness problems usually appear as overwritten content, repeated edits, or ownership confusion.

A stable operation model combines role separation, optimistic concurrency checks, and explicit lease ownership.

Pattern 1: Role-based control plane

A practical role split looks like this:

• Coordinator: plans tasks, assigns ownership, decides ordering.
• Worker: performs document-level execution.
• Auditor: validates revisions, events, and export outputs.

This split keeps each role focused and limits privilege overlap.

Pattern 2: Revision-safe write loop

For every write operation:

1. read_document and capture current revision.
2. Compute the intended mutation.
3. Call safe_update_document with expected_revision.
4. If conflict is returned, re-read, merge, and retry.

This prevents silent overwrite when another actor changed the document first.

Pattern 3: Lease ownership for hot documents

For high-contention documents, add lease ownership:

• acquire_document_lease
• renew_document_lease
• release_document_lease
• get_active_document_lease

For cross-process coordination, use data attribute strategy:

OUTLINE_LEASE_STRATEGY=data_attribute
OUTLINE_LEASE_ATTRIBUTE_ID=your_data_attribute_id

Pattern 4: Batch orchestration with boundaries

Batch tools improve throughput but require stronger boundaries.

Use batch operations when:

• The target scope is explicit and reviewed.
• Ordering requirements are known.
• Rollback strategy is defined.

Prefer dry-run style planning with read tools first, then run batch execution.

Pattern 5: Resource-first context loading

Before mutation, collect context from resources:

• outline://collection/{collection_id}/tree
• outline://document/{document_id}
• outline://document/{document_id}/backlinks

This reduces planning errors from incomplete context.

Incident response checklist

When something goes wrong:

1. Confirm permission profile and actor intent.
2. Inspect latest revisions and events.
3. Verify lease state for contested documents.
4. Retry only after conflicts are resolved explicitly.