Memory and multi-agent systems in TypeScript · 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
  • TypeScript
  • In the all labs plan

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

Why you need this

The four specialists work, and they hand conversations to each other. 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.

Handoffs pass a conversation from one agent to the next. They pass nothing sideways: a fact one specialist works out never reaches the others unless it is written somewhere they all read.

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.ts: a blackboard with owners

    Write and export owners(key) in blackboard.ts, 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. Export a class OwnershipError that extends Error, with its name set to 'OwnershipError'.

    Then export a class Blackboard on node:sqlite: new Blackboard(path, weddingId) opens or creates a table board with the columns wedding_id, key, value, by and at. read(key) returns the key's value for this wedding, or null; keys() its keys, sorted; write(key, value, by, { at }) 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 throws an OwnershipError and changes nothing. The check opens two Blackboards on one file, for two weddings.

  2. Task 2

    versions.ts: versions

    Write and export a class ConflictError that extends Error, with its name set to 'ConflictError', and a class VersionedBoard in versions.ts (it may build on task 1). new VersionedBoard(path, weddingId) 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, expectedVersion }) throws an OwnershipError when by may not write the key; when expectedVersion is given and is not the key's version it throws a ConflictError 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.ts: a log of every write

    Write and export a class LoggedBoard in log.ts, 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 an OwnershipError, or refused (version) for a ConflictError. A refused write is logged and still throws. log() returns the wedding's log, oldest first, each an object with key, old, new, by, at and outcome.

    Inside if (import.meta.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.ts: specialists on the blackboard

    In agents.ts, write and export seed(board, weddingId): it writes the wedding's current facts (baraat.ts's current) on the board, each by its owner from task 1. Then team(board): the four specialists as Specialist objects from specialists.ts, 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.ts.

    Then cateringQuote(board): the guest count times the booked caterer's veg_per_plate (baraat.ts's vendor), both read from the board, written as quote:catering by catering, and returned. Inside if (import.meta.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.ts, a lost update

    In fix-me.ts, specialists add notes about guests to one list on the board, guest_notes: each reads the list, awaits its model call, then writes the list back with its note. Run it: catering and venue run at once with Promise.all, both read the empty list, and the second write erases the first note.

    Fix addNote so that no note is ever lost, however many specialists run at once: write with the version you read, and when someone wrote first, read again and retry. work(note) is the specialist's model call between your read and your write; keep awaiting it there. Keep the function's name, its parameters and the export, and Board and ConflictError as they are. The check runs up to four specialists at once, with different delays.

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), and an error class of your own when it tries.
  • 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, in its async form, 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. You build its assistant in TypeScript. 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 in TypeScript are free. This one comes with the all labs plan.