What’s the difference between storing “messages,” “artifacts,” and “decisions” in state?

What you need to know

1class ReportState(TypedDict):2    messages: Annotated[list, add_messages]   # for the model3    draft: str                                 # artifact4    critique: dict                             # artifact: {approved, issues}5    revisions: int                             # decision6    approved: bool                             # decision

Why the separation matters

• Safe trimming — the summariser can drop 30 messages without touching revisions.
• Reliable routing — the edge reads approved: bool, not "does the last message contain the word approved".
• One source of truth — the current draft lives in draft, not in the fourth-last AI message.
• Testing — you can assert state["route"] == "needs_approval" in a unit test.
• Security — a customer's message cannot flip approved, because only the approval node writes that key.

A real-life example

A report-writing agent at a consulting firm drafts a client memo, a critic reviews it, and the writer revises up to twice. In version one, everything lived in messages, and the edge searched the last message for "APPROVED". When the critic wrote "Not approved yet — the revenue figure needs a source", the word matched and an unreviewed memo went to the client. Version two stores critique = {"approved": false, "issues": [...]} from structured output and routes on the boolean. The false approvals stopped, and the summary node could now trim messages freely.

Follow-up questions to expect

• "Should artifacts also appear in messages?" — Only when the model needs to read them in this step; format them into the prompt inside the node rather than storing them twice.
• "How do you keep an artifact's history?" — Checkpoint history already has every version; or keep a small append-only list of versions if the product needs it.
• "Who is allowed to write decisions?" — Specific nodes only, ideally from structured output or code, never parsed from free text.