cleandataengineering.aiAgent Harness, drawn simply
You are here: End to end › State & memory › The tables

Agent Harness Tutorial · End to end · Zoom level 2

The tables

All of it fits in one small Azure PostgreSQL server with two databases. The left one is ours. The right one belongs to the claims system; the harness never touches it directly.

DATABASE claims_agent · login claims_agentOpen: requestsrequeststhe ledgerzoom in ›Open: checkpointscheckpointsthe conversationzoom in ›sessionsencrypted refresh tokensOpen: approvalsapprovalspayouts waitingzoom in ›Open: escalationsescalationshand-offszoom in ›Open: schema dbos: 13 tablesschema dbos: 13 tablesworkflow status, step outputs, events, notificationszoom in ›DATABASE claims_fnol · login claims_systempolicyholderPH-1001policyPOL-010001claimCLM-019002claim_documente.g. police_firansweredits own ledgerthe claims login may read agent_state.approvals, and nothing else
Solid boxes are ours. Dashed boxes belong to the claims system and are reached only through its tools.
TableOne row isKey columns
requestsone message, or one write tool callname (the key), scope, state, outcome, expires_at
checkpointsthe conversation after one turnrun_id, conversation_id, customer_id, state (JSON)
sessionsone signed-in personsubject, refresh_token (encrypted with a Key Vault key)
approvalsone payout waiting for a personid (= the DBOS workflow id), action, args, status, decided_by
escalationsone hand-offid (E-…), question, found, missing, status, sla_due_at

Not built yet: tables for long-term memory, for document knowledge with vector search, and for online eval findings. They are designed in the Series.

Want every detail? The long version is in the Series: the data model, table by table.

How it is done: the real code

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

-- The agent's own state (Tier 2), in the agent's database (claims_agent),
-- beside the DBOS system tables the approval and escalation waits keep there.
-- Never the claims system's database: the agent reaches the claims system only
-- over MCP.
--
-- The tables the harness's PostgreSQL adapters write (agent_harness.state.postgres
-- and agent_harness.requests.postgres), as the reference agent's sql/001_schemas.sql
-- declares them. Applied by `claims_fnol_app.store.migrate`.

CREATE SCHEMA IF NOT EXISTS agent_state;

-- One row per run; read back by conversation (F-006), erasable by customer (F-056).
CREATE TABLE IF NOT EXISTS agent_state.checkpoints (
    run_id          text PRIMARY KEY,
    conversation_id text,
    customer_id     text,
    state           bytea       NOT NULL,
    updated_at      timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX IF NOT EXISTS checkpoints_customer ON agent_state.checkpoints (customer_id);
CREATE INDEX IF NOT EXISTS checkpoints_conversation
    ON agent_state.checkpoints (conversation_id, updated_at DESC);

-- One name, one outcome (T-062): the delivery claim and the tool-call ledger.
CREATE TABLE IF NOT EXISTS agent_state.requests (
    name        text PRIMARY KEY,
    scope       text        NOT NULL,
    state       text        NOT NULL,
    outcome     jsonb,
    expires_at  timestamptz,
    recorded_at timestamptz NOT NULL DEFAULT now()
);