Five shapes, four arrows
Lesson 2 of 6 in Whiteboarding Agent Systems: Drawing the Thing You Built.
The notation has to be small enough that you never pause to remember it, and expressive enough to answer the three questions every reviewer asks. Five shapes and four arrow types do it. Everything else is a word written next to a shape.
The organising idea is that the shape tells you who decides. That is the distinction agent systems live and die on, so it gets the most visible encoding on the board.
Three deliberate choices in there are worth defending, because each one is a question you will otherwise be asked.
Model calls get their own shape. Not because they are special technology, but because a round box means this output is not the same twice, and every claim about the system’s behaviour downstream of a round box is a claim about a distribution. Reviewers who see the shape stop asking “is it reliable” and start asking the better question: “what checks its output?”
Stores carry a lifetime, not a product name. # Postgres # tells the room nothing. # run state / one run, survives suspend # tells them what breaks if the process dies. The four-store distinction — model context, run state, case memory, system of record — is the thing you are communicating, and the lifetime label is what communicates it.
Irreversible effects get a mark, and the mark creates an obligation. Every ! on the board must have a failure arrow leaving it. That single rule converts a happy-path diagram into a design document, and it is why the sixth drawing step exists.
Why not just use a sequence diagram?
Use one when the order is the point — protocol negotiation, a multi-hop handoff, reconstructing an incident. Sequence diagrams are excellent at time and poor at control ownership: every participant gets an identical lane, so “code decides here, the model decides there” has no visual home. On a whiteboard you also pay a real cost for lanes, because adding a participant means redrawing.
The pragmatic split: shapes for architecture, lanes for time. Lesson five draws the same system both ways.
Why not C4, or a component diagram?
C4 is genuinely good and worth knowing — its levels give you a shared answer to “how zoomed in are we?”, which is the second most common cause of confused reviews. But a component diagram’s boxes are deployables, and an agent’s distinctive risks are not deployment properties. “The model decides which of these forty tools to call, and one of them moves money” is invisible in a diagram whose vocabulary is services and dependencies.
Use C4 for the system your agent lives in. Use this notation for the agent.
Where do data-flow diagrams fit?
They are the ancestor of the trust-boundary overlay in lesson four, and if you have done threat modelling you already know the move: processes, stores, flows, and a dashed line where data crosses a boundary. The overlay here is a DFD with agent-specific labels. If your organisation already runs threat models on DFDs, draw the overlay in their notation — matching the house style is worth more than a marginally better diagram.
Do I need colour?
No, and depending on it will hurt you: half the rooms you draw in have one working marker, and a photographed board loses colour distinctions that survived in person. Encode meaning in shape and written words, then use colour as redundant emphasis if you happen to have it. The same reasoning applies to anyone in the room with a colour-vision deficiency — the board should read identically in black and white.
Key terms: trust boundary, non-determinism, checkpoint, compensating action
Interactive checkpoint quiz (2 questions) — open this page in a browser to take it.