Human-in-the-loop

In one line. Agents do the volume, humans do the judgment — human-in-the-loop is the machinery that decides which documents a person must see, queues them, captures the correction, and records the decision, so you can trust the ninety percent nobody looked at. You’ll be able to. Trace a document from the confidence gate to the Inbox to a reviewer’s sign-off, and configure the three controls that govern all of it: the Auto-Decide policy, the per-stage Send to Inbox flag, and the role-gated four-eyes stages.

Why the loop exists

An agent that processes ten thousand invoices a day is only useful if someone can answer the question “why should I believe it?” Our answer is structural, not statistical: the platform never asks you to trust the model. It asks you to trust a process — one where AI recommends, confidence decides who looks, two humans confirm anything that matters, and every step is written down. The agent supplies throughput; the human supplies judgment; the lifecycle is the contract between them.

This division of labour is deliberate. If every document routes to a person you have built a manual queue with extra steps. If none do, you have removed the safety net. The whole design of human-in-the-loop is about routing only the doubtful documents to a person — and shrinking that set over time.

The confidence gate — what routes, and why

Every Processing collection is seeded with the eight-stage Four-Eyes lifecycle (Intake → AI Processing → AI Recommendation → L1 Review → L2 Approval → Needs Info → Approved / Declined — the full stage reference is in Taxonomy, lifecycle, tags & events). The fork in that road is AI Recommendation: after the intake agent extracts fields, each field carries a confidence score (0..1), and the document’s route depends on whether it clears the bar.

AI Recommendation
  │
  ├─ Auto-Decide ON and the doc passes (confidence ≥ 0.92,
  │  zero open flags, under the amount cap)
  │     └──► Approved / Declined        straight-through; audit actor: AI/auto
  │
  └─ everything else ──► L1 Review (Inbox) ──► L2 Approval (Inbox) ──► Approved / Declined
                            │      ▲
                            ▼      │ info arrives — re-runs AI Processing
                        Needs Info (Inbox)

Three kinds of documents reach a human: low-confidence extractions, documents with open flags (a failed validation, a mismatch), and anything the Auto-Decide policy is not allowed to touch. Clean documents settle themselves; doubtful ones wait for a person. That is the exception policy, and tuning it is most of the craft of running a workflow (the Workflow pattern walks the full build).

The Inbox — the queue

Documents that hit a human stage land in the Inbox (App ▸ Inbox) — the canonical Human-kind collection (Core concepts), the one list of everything waiting on a person in the project. When a document enters a stage whose Send to Inbox (human review) toggle is on, the server creates an InboxNote that wraps the source document — it carries the source collection, the document id, and the stage, and shows them on the card’s provenance line.

Items group into fixed sections — Needs Approval, Needs Review, Needs Info, To Triage, Tasks — with a My items / Everyone scope filter and an Open / Snoozed / Done status filter.

Watch out — the Inbox does not act on items. It is read + snooze + dismiss only. There is no approve, reject, or edit button in the Inbox. Each card is a pointer: click Open and you land on the wrapped document, where the real work happens. When you advance the document past its human stage, the Inbox item resolves itself — you never mark it done by hand.

Full queue mechanics — cards, snooze behaviour, empty states — are in Dashboards & inbox.

The reviewer’s loop — correct, approve, teach

The work happens on the document detail page (E3) — the split view with the document on one side and the extracted fields on the other. A reviewer’s loop is four moves:

Read the flagged fields first. Low-confidence values are flagged so your eye goes straight to what the agent is unsure of.
Verify against the source. Click a value and the viewer scrolls to the exact segment it came from and highlights it — the agent shows its work. This is how you catch a mis-read (a subtotal grabbed instead of the grand total) in one click.
Correct in place. Edit the wrong value; it saves back to the label. Rescore and Update {Lookup} Values re-derive anything that depends on it.
Advance. From the workflow action pane, perform the stage transition — approve forward, send back Needs Info, or reject.

The part builders underestimate: step 3 is not just fixing one document. Every correction is a labelled example the trainable extraction model learns from, so the agent extracts that field better next time. Reviewing is training. A review queue that shrinks over months is the visible result of corrections made today.

Role-gated. A subscription-viewer role gets a read-only summary — every field visible, nothing editable, no stage transitions. If fields will not edit, check the role before assuming a bug. Roles are covered in Access & roles.

Four eyes for decisions that matter

For consequential decisions, one reviewer is not enough — the Four-Eyes lifecycle enforces two. L1 Review is the first human eye; L2 Approval is the second, and the gate. The seed creates exactly two reviewer roles — L1-Reviewer (bound to L1 Review) and L2-Approver (bound to both review stages) — and each stage’s Can be viewed by control (ViewedByRoleIds) lets you tighten gating further. Because the transitions are role-gated, no single person can push a document from intake to approved. That is the four-eyes rule made structural rather than procedural.

Two details worth internalising:

Declined is terminal. The lifecycle has two End stages — Approved and Declined. A rejection is not a soft state to be quietly reversed; it closes the document out, on the record. If the process genuinely needs a way back, model it explicitly — Needs Info loops a document back through AI Processing when information arrives, and Allow Back Propagation on the lifecycle lets L2 send a document back to L1.
Sign-off is also an API. The same stage transition a reviewer performs in the UI can be performed programmatically through the Runtime API (V1) — same gate, same audit row — for teams that integrate approval into their own systems.

Below the stage graph on the Lifecycle tab sits the Auto-Decide policy card — the single knob for straight-through processing. It is off by default: until you enable it, every document visits L1 and L2. Switched on, it auto-promotes documents that pass all its gates:

Field	Default	Meaning
Enabled	`false`	Master switch.
Min Confidence	`0.92`	Agent confidence floor required to auto-promote.
Require Zero Flags	`true`	Any open flag on the document blocks auto-promotion.
Max Amount	`null`	A monetary ceiling, read from the Amount Field; `null` = no cap.
Applies To	`both`	Which verdicts may auto-fire: `approve` / `decline` / `both`.

The card previews the policy in plain English — “Auto-approve when AI confidence ≥ 0.92 AND zero flags AND amount ≤ $500k.” The safest opening move is Enabled = true, Applies To = approve: auto-approve clean cases, keep human eyes on every decline.

The straight-through share is not fixed — it compounds. Corrections from the reviewer’s loop train the extractor, trained extractors produce higher confidence, and higher confidence pushes more documents past the gate. A workflow that starts at full manual review and ends with most volume straight-through, humans handling only genuine exceptions, is the system working as designed. The review-rate trend is worth a dashboard widget (Dashboards & inbox): a falling rate is your model improving; a rising one is an early warning that something upstream changed.

What gets recorded

Every stage move — human or automatic — appends a row to the document’s audit trail (document_workflow_history): who moved it, when, from which stage to which, with what note. There is no separate “decision” object on the platform; the decision is that trail, read back. Auto-decide never spoofs a user: an auto-decided move is recorded under the auto-decide system actor with the confidence in its reason, and every audit row stores an actor kind — human, agent, system, or api-key — so a machine’s move can never read as a person’s. The whole story is one click away: the document’s Audit trail side-sheet shows the full timeline, stage moves included. When an auditor asks who approved an invoice and on what basis, the answer is a query, not an investigation — the full compliance picture is Audit & compliance.

The three places you configure it

Everything above reduces to three controls, all reachable from Studio ▸ Data Model ▸ Collections ▸ <collection>:

#	What you are setting	Where	The control
1	The straight-through gate	Lifecycle tab, below the stage graph	The Auto-Decide policy card — Enabled, Min Confidence, Require Zero Flags, Max Amount, Applies To
2	Which stages queue for a human	Each stage’s Create / Edit State dialog	Send to Inbox (human review) — this is `IncludeManualIntervention`, the flag that makes a stage a review stage
3	Who may act at each gate	The same stage dialog	Can be viewed by (`ViewedByRoleIds`) plus the `L1-Reviewer` / `L2-Approver` roles on the four-eyes stages

Set those three deliberately and you have defined the entire human contract of your workflow: what skips people, what waits for them, and who is allowed to decide.

Where to go next

Taxonomy, lifecycle, tags & events — the full Lifecycle tab reference the three controls live in.
Document detail — the page your reviewers will live in.
Audit & compliance — the record every stage move leaves behind.
Invoice processing — a worked build where this loop runs end to end.