cleandataengineering.aiAgent Harness, drawn simply
You are here: End to end › State & memory › Inside a checkpoint

Agent Harness Tutorial · End to end · Zoom level 2

Inside a checkpoint

A checkpoint is one row saved at the end of each turn. It holds the conversation's text and a few short notes the code uses to behave sensibly next time.

checkpoints row · run_id · conversation_id cnv_… · customer_id PH-1001 · updated_atmessagesRohan's words andthe replies, ≤ 32,000 charsrecentup to 12 turn notes:route, result, endingfactsasked · read · done· awaitingpendingapproval id?escalation id?countersturns, hand-offsraised (max 2)
The whole thing is one JSON value in the state column.

Facts are notes for the code, not for the model: what Rohan asked, which rows were read, which writes were done (such as register_claim:POL-010001), and what is awaiting his "yes". They let the harness re-read the right rows and honour a plain "yes" without trusting the model.

Pending ids point to a payout waiting for approval or a hand-off waiting for a person. The front door checks them before anything else on the next turn.

Resuming. When Rohan opens the chat page, the newest checkpoint is resumed if it is under 24 hours old, or if something is still pending.

Forgetting. Rows older than 30 days are deleted, and one person's rows can be erased on request. Both are built; running them on a schedule on Azure is not yet.

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

Goes inThe stored conversation and the customer's new message
What happensThe turn records what was asked, what the far system confirmed, what was read and what someone else now holds, each as a new frozen copy
Comes outAn updated Conversation whose Facts survive into the next turn
CALL STACK · START TO FINISHGOES IN → COMES OUT1Open the source: claims_fnol/entrypoint/__init__.py:178Agent._turn(text, identity, conversation, run_id, gone)claims_fnol/entrypoint/__init__.py:178in: message and the stored conversationout: result and the persisted conversation2Open the source: claims_fnol/entrypoint/__init__.py:234Agent._gates(conversation, identity, run_id)claims_fnol/entrypoint/__init__.py:234in: pending escalation / approval idsout: a held result, or None to proceed3Open the source: claims_fnol/router/concerns.py:25concerns(text)claims_fnol/router/concerns.py:25in: the customer's messageout: one concern per clause4Open the source: agent_harness/state/facts.py:85Facts.asking(text, concerns)agent_harness/state/facts.py:85in: their own words and concernsout: Facts with asked and concerns set5Open the source: agent_harness/state/__init__.py:166Conversation.with_messages(*added)agent_harness/state/__init__.py:166in: the user messageout: conversation with the message appended6Open the source: claims_fnol/entrypoint/__init__.py:261Agent._dispatch(decision, conversation, identity, run_id, g…claims_fnol/entrypoint/__init__.py:261in: the route decisionout: result plus landed, tried and read pairs7Open the source: agent_harness/state/__init__.py:69TurnNote.of(decision, result)agent_harness/state/__init__.py:69in: route and resultout: a TurnNote (route, result, intent)8Open the source: agent_harness/state/__init__.py:194Conversation.with_turn(note)agent_harness/state/__init__.py:194in: the TurnNoteout: recent notes and turn_count updated9Open the source: agent_harness/state/facts.py:138after(facts, result, landed, looked)agent_harness/state/facts.py:138in: confirmed effects and answered readsout: Facts with done, read, awaiting10Open the source: agent_harness/state/facts.py:102Facts.landed(operation, record)agent_harness/state/facts.py:102in: an effect the far end confirmedout: done gains operation:record11Open the source: agent_harness/state/facts.py:93Facts.reading(tool, record)agent_harness/state/facts.py:93in: a read that answeredout: read gains tool:record, sorted12Open the source: agent_harness/state/facts.py:108Facts.waiting_on(kind, identifier)agent_harness/state/facts.py:108in: NeedsApproval or Escalated resultout: awaiting gains approval:/escalation: id13Open the source: claims_fnol/entrypoint/consent.py:74pending(facts, attempted, identity)claims_fnol/entrypoint/consent.py:74in: facts and the calls attemptedout: facts with consent still owed14Open the source: agent_harness/state/__init__.py:203Conversation.recording(result)agent_harness/state/__init__.py:203in: the screened resultout: reply appended; pending ids set
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/__init__.py:98What one checkpoint row holds
class Conversation(BaseModel):
    """What survives between turns.

    Deliberately not the whole trace: spans are for explaining a past run, this
    is for continuing one. Keeping them apart is what stops a checkpoint growing
    without bound.
    """

    model_config = ConfigDict(frozen=True)

    conversation_id: ConversationId
    customer_id: str
    messages: tuple[Message, ...] = ()
    recent: tuple[TurnNote, ...] = ()
    """The last few turn outcomes, newest last, capped at `RECENT_TURNS`.

    Added for Tier 2 escalation, which asks how the conversation is *going* —
    and nothing here recorded that. The messages hold what was said; these hold
    what happened, and no rule can be written over the first."""
    turn_count: int = 0
    """Every turn, not just the remembered ones. `len(recent)` stops at the cap
    and a rule about a long conversation needs the real number."""
    escalated_rules: tuple[str, ...] = ()
    """Which rules have fetched a person since the agent last took the
    conversation back — from its start, or from the latest return.

    The cooldown, in storage terms (`P-ESC-ONCE`). A Tier 2 condition does not
    stop holding because an escalation lapsed, so without this the same rule
    would raise, lapse and raise again for as long as the customer kept talking.
    Emptied by `returned`, because what happens after a colleague hands the
    conversation back is new evidence; `escalations_raised` is what stops a
    loop, and it is never emptied. Which rule raised each escalation stays on
    the escalation's own record."""
    returned_at_turn: int = 0