The Messages API has no memory of its own. Every call is a complete, self-contained request: you resend the whole conversation, and the model's only knowledge of anything that happened before is whatever text sits in that history. That statelessness is a feature -- it is what makes a request retryable, cacheable, and safe to route to any server behind a load balancer -- but it describes the model's contract, not the systems the model's tools actually touch.
A tool that opens a database transaction, holds a cursor open on a slow query, reserves a seat on a flight, or starts a checkout session has created real state the instant it runs. That state does not live in the conversation history. It lives on a server, in a row, in a lock -- and the model has no way to see it except through what a future tool result chooses to tell it. The model did not become stateful. The tool's side of the world did, and now someone has to manage the gap between the two.
This lesson is about that gap: where state can safely live when a tool's effects outlast a single call, how to make that state a first-class, visible thing rather than an assumption baked into a handler, and what breaks when retries, concurrency, or an abandoned run collide with state nobody remembered to clean up. Every pattern here connects directly back to the idempotency guard from lesson 04 and the independence assumption from lesson 10 -- this is where both assumptions get tested by state that persists between calls instead of disappearing when a single call returns.
Analogy🏏Cricket
🏏 Think of it like cricket: the ground announcer at Eden Gardens gets a walkie-talkie message from the boundary umpire after every ball -- 'four, cover drive, Gill' -- and reads it out. The announcer's booth has no memory between messages; whatever isn't in this ball's message doesn't exist as far as the booth is concerned. But the real match is not stateless at all. Somewhere on the ground, a scoreboard operator is tracking the actual state: 187 for 3, India have one DRS review left in this innings, Bumrah is two overs into a fresh spell. None of that lives in the walkie-talkie feed. If the boundary umpire forgets to mention the review count in his next message, the announcer has no way to recover it -- he only ever knew what was said to him, ball by ball. This is the exact shape of the tool-use loop: the Messages API is the walkie-talkie, stateless by contract, repeating back only what you hand it each turn. The scoreboard -- the database row a tool just locked, the payment it just charged, the session it just opened -- is the real state of the match, sitting on a system the model cannot see and was never told exists unless a tool result says so explicitly. A tool that opens a transaction, holds a cursor, or reserves a seat has, in that instant, become a scoreboard operator the announcer's booth doesn't know is there -- and the model, hearing only what comes back next turn, has no more visibility into it than a walkie-talkie listener has into the reviews actually left.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.