Blackboard / shared-artifact architectures

Read these first

• Swarm / handoff

What you will know

• Have agents coordinate through a shared file or task list

  Define a schema for ownership, status, inputs, outputs, and completion so another agent can act without guessing what the latest state means.

• Measure how artifact inspection changes run reconstruction time and error rate versus a message transcript

  Use the same failed scenarios and observers for both designs; inspectability only matters if it reduces time to locate the blocking or incorrect decision.

• Handle two agents writing to the same artifact

  Test simultaneous updates, stale reads, retries, and partial writes using leases, compare-and-swap, append-only events, or another explicit conflict policy.

• Show a human reading the blackboard to understand the run

  A reviewer should be able to identify the current owner, pending work, last successful transition, and recovery action without consulting hidden logs.

• Compare it against message passing on a real task

  Hold the task and agents constant while comparing completion quality, coordination overhead, recovery after failure, and state freshness.

Chapters

1. 1

   The run's state lives in the file, not in flight

   Three agents can hand each other structured payloads, or all three can read and write one run.json holding the task list, ownership and pointers to each stage's output. The difference is where the run's state sits when a process dies. Note what a blackboard is weakest at: it holds current state, not history, so unless events are appended deliberately it carries less of the past than a logged message did.

   Read chapter
2. 2

   A done flag is a claim, not a result

   Four agents share a tasks.json whose entries carry only a title and a done boolean. Agents start work someone else is already doing, and entries marked done have no usable output anywhere. Separate ownership from status, record who holds an item and since when, name the inputs it needs and where its output was written, so the next reader can check the claim rather than trust it.

   Read chapter
3. 3

   Two whole-document writes in the same second lose one

   Each agent reads the file, edits its own section in memory and writes the whole document back; two finishing together means one update simply disappears while the run reports success. Make each write conditional on the version that was read, and have the loser re-read and reapply. A plain lock is worse than it looks here, because the critical section spans a four-minute turn and a crashed holder never releases it.

   Read chapter
4. 4

   A half-written run.json passes every version check

   Compare-and-swap only orders writes that completed; it says nothing about a process that died with the file open. Truncated JSON, a retry after a write whose outcome you never learned, and a reader that already acted on a view that has since moved on are three separate failures with three separate fixes: replace the artifact atomically by writing a temporary file and renaming it, make each update carry an identifier so applying it twice is the same as applying it once, and give a stale reader a way to detect that it acted on an old version and undo or re-derive. In a design where the artifact is the only surviving copy of the run, a torn write loses the run outright.

   Read chapter
5. 5

   Leases, compare-and-swap and one designated writer fail differently

   Compare-and-swap detects conflicts but makes losers redo work, so it degrades as contention rises. A lease grants exclusive claim on an item with an expiry, so a crashed holder is reclaimed rather than blocking forever, at the cost of a stolen item finishing twice. Append-only events remove write conflicts entirely and buy back the history a blackboard lacks, but every reader now has to fold the log into current state. Routing all writes through one designated writer is not a lock and escapes the coarse-lock critique, yet it rebuilds the central coordinator the blackboard was chosen to avoid, becomes a single point of failure and a queue, and still leaves the stale-read half untouched, because agents compute their updates from views that may be out of date by the time the writer applies them.

   Read chapter
6. 6

   What the blackboard must tell on-call at 2am without logs

   A run has produced nothing for twenty minutes. For the artifact to have earned its place in the design, the engineer opening it must establish who owns each outstanding item and how long they have held it, what the last successful transition was, and what recovery action is available, without opening a single agent's log to work any of it out. That requirement shapes the schema more than any elegance argument.

   Read chapter
7. 7

   Faster diagnosis and more confident misdiagnosis arrive together

   You justified the migration on the claim that failed runs become quicker to diagnose, so test it: replay the same failures under both designs, give matched observers one representation each, and measure both time to name the blocking decision and how often they name it correctly. Speed alone is not the result you wanted. A tidy current state with its transitions hidden invites a confident story about a run nobody reconstructed.

   Read chapter
8. 8

   Shared state survives the worker that crashed holding it

   Move a document pipeline off messaging and throughput may not change, while runs that hit a crashed worker start finishing: a replacement reads the artifact and resumes from the last recorded transition, where before the only copy of that state was in flight. Hold the task and the agents constant to see it. Direct messages still win when a result has exactly one consumer and no reader after it.

   Read chapter
9. 9

   Moving untyped fields into a shared file reproduces every handoff bug

   A team proposes that nine agents coordinate only through state.json, citing on-call readability and three incidents caused by lossy payloads. Those incidents came from fields with no typed constraints, and relocating the same fields gives nine readers the chance to interpret each one differently. Their claim that concurrency is moot because a scheduler dispatches sequentially expires the day somebody wants the system faster.

   Read chapter