cleandataengineering.aiAgent Harness, drawn simply
You are here: End to end › State & memory › Step by table

Agent Harness Tutorial · End to end · Zoom level 2

Which step touches which table

Follow one turn down the page and watch which table each step touches. The pattern is simple: read once at the start, guard each write in the middle, save once at the end.

Open: Front doorFront doorzoom in ›1read newest checkpointcheckpointsOpen: Front doorFront doorzoom in ›2insert delivery row, in_flightrequestsOpen: Anything waiting?Anything waiting?zoom in ›3read pending approval / hand-offapprovals, DBOSOpen: Router and model callsRouter and model callszoom in ›4nothing—Open: Each write toolEach write toolzoom in ›5insert tool row firstrequestsOpen: SaveSavezoom in ›6insert or update the checkpointcheckpointsOpen: SettleSettlezoom in ›7delivery row → answered + replyrequests
Model calls touch no table at all.

The checkpoint is saved once per turn, with "insert, or update if this run id is already there", so a retried save can't make a duplicate.

The delivery row is always settled, even when the turn failed, so a retry of the same message gets the same answer rather than running again.

Not built yet: saving a checkpoint after every trip of the loop (today it is once per turn), and an outbox so the reply and the checkpoint are written in one transaction.

Code view: input, process, output, the call stack, the classes

Goes inA chat request that may name an earlier conversation
What happensThe newest checkpoint of that conversation is loaded at the start; at the end the history is bounded and written as one row per run, and the delivery claim is settled
Comes outA checkpoint row in agent_state.checkpoints and a settled delivery
CALL STACK · START TO FINISHGOES IN → COMES OUT1Open the source: agent_harness/serve/__init__.py:203chat(request)agent_harness/serve/__init__.py:203in: POST /chat body and bearer tokenout: JSON reply inside an http.chat span2Open the source: agent_harness/serve/__init__.py:234_conversation_for(store, inbound)agent_harness/serve/__init__.py:234in: conversation_id from the bodyout: the Conversation, None, or _NotYours3Open the source: agent_harness/state/postgres.py:124PostgresCheckpointStore.latest(conversation_id)agent_harness/state/postgres.py:124in: the conversation idout: newest state bytes, by updated_at4Open the source: agent_harness/state/__init__.py:235Conversation.decode(raw)agent_harness/state/__init__.py:235in: stored bytesout: a Conversation (owner checked after)5Open the source: agent_harness/serve/__init__.py:252_run_turn(agent, inbound, conversation, span, gone=)agent_harness/serve/__init__.py:252in: inbound and the loaded conversationout: JSON response with status code6Open the source: claims_fnol/entrypoint/__init__.py:141Agent.handle(text, *, identity, conversation, delivery_…claims_fnol/entrypoint/__init__.py:141in: text, identity, conversationout: (TurnResult, stored Conversation)7Open the source: agent_harness/requests/postgres.py:37PostgresRequests.claim(name, scope=Scope.DELIVERY)agent_harness/requests/postgres.py:37in: customer_id:delivery_id, via req.onceout: a Claim held for the turn8Open the source: claims_fnol/entrypoint/__init__.py:178Agent._turn(text, identity, conversation, run_id, g…claims_fnol/entrypoint/__init__.py:178in: the turn's inputsout: result and the persisted conversation9Open the source: agent_harness/state/__init__.py:203Conversation.recording(result)agent_harness/state/__init__.py:203in: the turn's resultout: reply appended; pending ids remembered10Open the source: claims_fnol/entrypoint/__init__.py:355Agent._persist(run_id, conversation)claims_fnol/entrypoint/__init__.py:355in: run id and the updated conversationout: what TurnPersister stored11Open the source: agent_harness/entrypoint/persist.py:34TurnPersister.persist(run_id, conversation)agent_harness/entrypoint/persist.py:34in: the conversationout: the bounded copy that was stored12Open the source: agent_harness/context/__init__.py:191bounded(history, *, max_chars)agent_harness/context/__init__.py:191in: messages and history_charsout: messages that fit, oldest dropped13Open the source: agent_harness/state/postgres.py:58PostgresCheckpointStore.checkpoint(run_i…agent_harness/state/postgres.py:58in: encoded state, conversation and customer idout: INSERT ... ON CONFLICT (run_id) DO UPDATE14Open the source: agent_harness/requests/postgres.py:77PostgresRequests.settle(name, outcome)agent_harness/requests/postgres.py:77in: the delivery name and as_answer()out: delivery row set to answered
Read top to bottom: each box is one function call, indented under the function that called it; the dark box is where it starts. Click a box to open its source file.
Dashed boxes are protocols (the ports) or enums; grey boxes are data models; white boxes are classes with behaviour. A dashed arrow means "implements". Click a class to open its source.

How it is done: the real code

Cut from the live repositories each time the site is built, so it always matches what runs.

agent_harness/state/postgres.py:77Save the checkpoint: insert, or update if this run already saved
                ON CONFLICT (run_id) DO UPDATE
                    SET state = EXCLUDED.state,
                        conversation_id = EXCLUDED.conversation_id,
                        customer_id = EXCLUDED.customer_id,
                        updated_at = now()
                """,