Explicit State

Last chapter’s refund story broke a simple loop when the amount was large: you needed a branch, and later a pause.

Under that pain was another problem: the facts of the job lived in loose variables and chat text.

This chapter fixes that with one idea: explicit state.

Same story, clearer memory

Person’s question: “Please refund order 4412.”

Facts you must not lose:

If these live only in your head, or only in scattered variables, a branch will forget one.

What state means

State is one object that holds those facts.

Every step of the workflow:

1. Reads state
2. Does a little work (maybe call the model)
3. Writes updates back into state

         ┌─────────────────┐
         │     STATE       │
         │  order, amount  │
         │  size, approved │
         │  status, reply  │
         └────────┬────────┘
                  │
     lookup ──► decide ──► refund or wait
        │          │              │
        └──────────┴──────────────┘
           each step reads / writes STATE

You do not hunt for “where did I put the amount?” It is always in state.

Before vs after

Before (scattered):

order_id = "4412"
amount = 900
# later, in another function…
# did we remember amount? approved? status?

After (explicit state):

state = {
  "order_id": "4412",
  "amount_usd": 900,
  "size": null,
  "approved": null,
  "status": "start",
  "reply": null
}

Same facts. One home.

Walk the refund with state

Start:

status: start
order_id: 4412
amount_usd: 900
size: (empty)
approved: (empty)

Step — lookup
Fill amount from your “order file.”
Write status: looked_up.

Step — decide
Ask the model: SMALL or LARGE?
Write size: LARGE, status: needs_approval.

Step — cannot refund yet
approved is still empty.
Write a clear reply: needs human approval.
Stop this run — but state still holds the truth.

Tomorrow, when a human says yes, you will set approved: yes and continue. You will not guess the amount again from chat noise. (Saving state to disk comes in a later chapter. Today we only make the object.)

Small amount path:
size: SMALL → refund → status: done, reply: Refunded $12…

Why this helps the model too

You can build the prompt from state:

Order: 4412
Amount: 900
Size: LARGE
Approved: not yet

Write a short status for the customer.

The model sees a clean snapshot. You are not hoping it “remembers” from a messy loop history alone.

Chat history can still exist. State is the source of truth for the workflow.

Rules that save pain

What is next

State alone does not draw the fork. Next chapter: Branching and Graphs — named steps and “go here next” using this state.

Then: save state and wait for a human.

Words to keep

See it in Code

The Code panel runs the refund steps while printing the state after each step. Watch fields fill in. Check the Example console.