HITL (Human-in-the-loop)

// 60-second mental model

How to hold it in your head

The agent may prepare everything — draft, plan, tool args — but an irreversible or high-stakes step waits for an explicit human approve (or reject). No silent auto-ship.

HITL inserts an approval gate before side effects: the runtime pauses with a structured proposal; a human returns approve|reject|edit; only then does the irreversible action run. Preparation is automatic; commitment is not.

// Mini architecture

Prepare → pause for human → commit or abort

┌──────────────┐
│ Agent        │ → proposal (draft / plan / args)
└──────┬───────┘
       ▼
┌──────────────┐
│ HITL gate    │ ── wait → human: approve|reject|edit
└──────┬───────┘
       │
       ├─ approve → Execute side effect
       ├─ edit    → Agent revises → gate again
       └─ reject  → Abort (no side effect)

If the side effect can run without the gate firing, you do not have HITL — you have a log.

// Mini-project

Refund proposal with approve gate (stub)

Agent stub + HITL gate stub (no real money)

Goal: Draft a refund proposal; block until a stub human returns approve|reject|edit; only then call `execute_refund` stub.

1. Agent builds `{ amount, reason, customerId }` from a canned ticket.
2. Call `request_approval(proposal)` — gate holds; do not execute yet.
3. Stub human returns edit once (lower amount), then approve.
4. On approve only, call `execute_refund` stub; log the approval id.
5. On reject, abort with no execute call.
6. Assert execute never runs without a recorded approval.

Stubs only — no real refunds. The contract is the gate. A studio parallel for taste: essay drafts wait for a human approve before publish tooling runs; that is HITL on commit, not an eval suite.

// Common failure

What goes wrong

// Self-reflection

Sit with this

Which irreversible step in your stack still has no human gate — only a hopeful prompt?