Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 27 of 37

Communication & shared state

0 of 37 complete

Why it matters

Two agents working on one task must agree on what is true: the goal, the constraints already satisfied, the artifacts produced. When each keeps its own copy of the plan, the copies diverge and the run produces two incompatible results. The engineering problem is to choose an authority for each fact, define who may write it, and make disagreement detectable rather than silent.

Mental model

Shared state is a whiteboard in a room; messages are notes passed under the door. The metaphor breaks because a whiteboard write is visible instantly, while a store write may not reach another agent for seconds and two writers can overwrite each other.

How it works

Messages copy, a plan is sharedInteractive

Two channels, one authority: instructions travel as messages, facts live in the shared plan.

Step 1/5 · Read the shape

Step 1 of 5

Read the shape

Six nodes, two channels. Message edges copy context into a recipient; store edges converge on one authority. The whole graph is lit so the shape, not one path, is the first thing seen.

Narrow layout: nodes in reading order, each followed by its outgoing edges. The wide drawing shows the same graph as geometry.

    agent

    5 connections

    Planner

    owns the plan

    Decomposes the task and owns the plan key. Message passing would copy the plan into each recipient; the store keeps one version that every reader resolves.

callasyncreturnconflictwider stroke + "this step" = current path

user · agent · store · 6 nodes · 10 edges · fixed authored layout, no simulation · list

Figure. Agents coordinate through two topologies at once. Message edges copy context into a recipient's prompt, so the same plan exists in several versions; the shared plan is one node every writer reaches, which turns disagreement into a write conflict. The conflict edge is the lost update: a write without a version check overwrites the plan another agent is still acting on.

What to notice. Message edges form a copy network, store edges converge on one authority, and the artifact store replaces a transcript with a reference. The figure omits transport (bus, queue, retries), the full message schema beyond sender and intent, and all token counts. Agent names, version numbers and the run id are illustrative; the topology is the claim.

Text version

Six nodes. A requester connects to a planner; the planner connects to a researcher and to a writer; the researcher and planner reply along return edges. A shared plan sits to the right, written by the researcher and the planner, read by the writer, with a conflict edge from the writer labelled clobber. An artifact store below receives the researcher's artifact and returns a reference to the writer. Steps light, in order: the whole graph; the message copies including a full transcript to the writer; the shared-plan authority; the lost update with the conflict edge; and the artifact reference path.

  1. Separate facts from instructions: facts belong in shared state, instructions belong in messages.
  2. Give every message a schema with sender, recipient, intent, payload and a correlation id.
  3. Store large artifacts once and pass references; copy only what the receiver must read verbatim.
  4. Allow one writer per key, or use a version check, so concurrent updates cannot clobber each other.
  5. Bound message size and summarise at the boundary, recording which fields were dropped.
  6. Log both directions of every exchange against one run id so a disagreement can be reconstructed.

Trade-offs

ChoiceGood forCostFails when
Messages onlyLoose coupling, easy fan-outDuplicated context and drift between copiesAgents must maintain a shared plan
Shared state storeOne source of truth, auditableConcurrency control and schema migrationWriters are long-running and uncoordinated
Full transcripts in messagesNo information lossToken cost grows with historyRuns are long and context is tight
Summarised handoffsCheap, focused contextDetail is lost irreversiblyThe receiver needs exact values or ids
Trade-off mapInteractive

Good for

Loose coupling, easy fan-out

Cost

Duplicated context and drift between copies

Fails when

Agents must maintain a shared plan

  1. Agents must maintain a shared plan
  2. Writers are long-running and uncoordinated
  3. Runs are long and context is tight
  4. The receiver needs exact values or ids

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Messages only is good for Loose coupling, easy fan-out, costs Duplicated context and drift between copies, and fails when Agents must maintain a shared plan. Shared state store is good for One source of truth, auditable, costs Concurrency control and schema migration, and fails when Writers are long-running and uncoordinated. Full transcripts in messages is good for No information loss, costs Token cost grows with history, and fails when Runs are long and context is tight. Summarised handoffs is good for Cheap, focused context, costs Detail is lost irreversibly, and fails when The receiver needs exact values or ids

Failure modes

  • Divergent copies. Two agents hold different versions of the plan and act on both. Debug: hash the shared plan at each step and assert exactly one version per run.
  • Lost detail in summary. The receiving agent invents a value the transcript contained. Debug: diff the summary against the source and check required fields survive.
  • Unordered messages. A reply arrives before the request it answers and the state machine stalls. Debug: assert monotonic sequence numbers per conversation.

In production

Monitor message volume, payload size and the age of each shared key, and cap fan-out per run. Rehearse a partition between agents to confirm the run stalls cleanly instead of proceeding on stale state.

Common misconceptions

People think: Shared state removes the need to coordinate.

Actually: A shared store moves coordination into write conflicts and read staleness; it does not delete it.

People think: More context in each message always helps.

Actually: Unfocused context dilutes attention and costs tokens; a reference plus a precise question usually beats a transcript.

Interview angle

Strong answers separate transport from semantics: what is authoritative, who may write it, how a reader knows it is current, and what happens when two agents disagree. Mention schema, correlation ids and the lossiness of summarisation. Weak answers describe a framework's message bus and never say which copy of the plan wins.

Sources