Memory and multi-agent systems · Chapter 12 of 16

Shared state

By the end of this chapter you can give a team of agents one place to keep what they know: a blackboard every specialist reads, where only the owner of a fact may write it, where every key has a version so two agents cannot quietly undo each other, and where every write, refused or not, is logged. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Many agents
  • 5 tasks
  • Python
  • In the all labs plan

The first 2 chapters of Memory and multi-agent systems are free. This one comes with the all labs plan.

Why you need this

The four specialists work. Each reads its own copy of the wedding's facts, built when it was made. Then Sameer asked the budget specialist for WD1057 "How much will the catering cost?" and got the sheet's estimate from June:

catering: Punjab Grill Caterers, estimate ₹22,41,000, paid ₹6,72,300.

The catering specialist had worked out a new quote that morning, for the new guest count. The budget specialist could not see it: the quote lived in another agent's head. Rekha has the opposite worry: "If every agent can change every fact, which one changed the caterer?" And Pooja wants the answer to one question for any fact: who wrote it, when, and what it was before.

What you build: 5 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    blackboard.py: a blackboard with owners

    Write owners(key) in blackboard.py, the set of names that may write a key: venue for a key ending in _venue or _date; catering for caterer, quote:catering and keys starting with diet:, allergy: or menu:; decor for decorator, theme, photographer and quote:decor; planner for budget and guests; all four specialists (venue, catering, decor, budget) for guest_notes; nobody (an empty set) for anything else.

    Then a class Blackboard: Blackboard(path, wedding_id) opens or creates a SQLite table board with the columns wedding_id, key, value, by and at. read(key) returns the key's value for this wedding, or None; keys() its keys, sorted; write(key, value, by, at=None) stores the value as JSON text, who wrote it and when (at, or the time now), one row per wedding and key. When by may not write the key, write raises PermissionError and changes nothing. The check opens two Blackboards on one file, for two weddings.

  2. Task 2

    versions.py: versions

    Write an exception Conflict and a class VersionedBoard in versions.py (it may build on task 1). VersionedBoard(path, wedding_id) keeps a SQLite file as task 1; read(key) and keys() as task 1; version(key) is the key's version, 0 before anyone writes it, one more after every write.

    write(key, value, by, at=None, expected_version=None) raises PermissionError when by may not write the key; when expected_version is given and is not the key's version it raises Conflict and changes nothing; otherwise it writes and returns the new version. The check uses two VersionedBoards on one file, like two specialists working at once.

  3. Task 3

    log.py: a log of every write

    Write a class LoggedBoard in log.py, a VersionedBoard whose write also adds a row to a table board_log: the wedding id, the key, the old value (what the key held before), the new value, by, at and the outcome: written, refused (owner) for a PermissionError, or refused (version) for a Conflict. A refused write is logged and still raises. log() returns the wedding's log, oldest first, each a dict with key, old, new, by, at and outcome.

    Under if __name__ == "__main__":, start a fresh log.db, play SCRIPT (keep it as it is) on a LoggedBoard for WD1042, carrying on after every refusal, and print one line per log entry: characters 11 to 16 of at, a space, who, a space, the key, a colon, a space, the old value as JSON text, a space, an arrow made of a hyphen and a greater-than sign, a space, the new value as JSON text, a comma, a space and the outcome, for example 09:00 planner guests: null -> 320, written

  4. Task 4

    agents.py: specialists on the blackboard

    In agents.py, write seed(board, wedding_id): it writes the wedding's current facts (baraat's current) on the board, each by its owner from task 1. Then team(board): the four specialists as Specialist objects from specialists.py, with the same names, descriptions and instructions as specialists(), each one's data being Notes:, its facts read from the board as dash, key, colon, value lines sorted by key, then everything specialists() puts after its notes. The budget specialist's facts are budget, guests and every key starting with quote:; the others' are the same as in specialists.py.

    Then catering_quote(board): the guest count times the booked caterer's veg_per_plate (baraat's vendor), both read from the board, written as quote:catering by catering, and returned. Under if __name__ == "__main__":, start a fresh agents.db with a VersionedBoard for WD1042, seed it, print quote:catering:, a space and the quote, then print the budget specialist's answer to How much will the catering cost? for WD1042.

  5. Task 5 · interview question

    Interview: fix_me.py, a lost update

    In fix_me.py, two specialists add notes about guests to one list on the board, guest_notes. Run it: catering reads the list, venue adds its note in the meantime, catering writes its own list back, and venue's note is gone.

    Fix add_note so that no note is ever lost, however the turns interleave: write with the version you read, and when someone wrote first, read again and retry. meanwhile() is the other specialist's turn, between your read and your write; call it as add_note does now. Keep the function's name and parameters, and Board as it is. The check interleaves several specialists' notes.

What you will learn

  • A blackboard: one shared store of facts that every agent reads.
  • Ownership: only the specialist that owns a fact writes it (policy.md, 6.2).
  • Versions and optimistic concurrency: a write that insists on the version it read.
  • A log of every write and every refusal.
  • The lost update, the classic bug of shared state, and its fix.

More in Many agents

Build "Shared state" yourself

Baraat Bliss, a Jaipur wedding planner, must remember months of family decisions across many agents. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Memory and multi-agent systems are free. This one comes with the all labs plan.