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 setting, and the persona-gated four-eyes stages. Where this lives. Studio ▸ Data ▸ Collections ▸ <collection> ▸ Lifecycle, with the queue itself at App ▸ Inbox.

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 starts 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 between 0 and 1, and the document’s route depends on whether it clears the bar.

AI Recommendation
  │
  ├─ Auto-Decide ON and the doc passes (confidence ≥ 92%,
  │  zero open flags, under the amount cap)
  │     └──► Approved / Declined        straight-through; recorded on the document timeline
  │
  └─ 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) setting is on, an item appears in the Inbox pointing back at the document, showing which collection it came from and which stage it is waiting at.

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 document it points at, 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, and anything derived from it recomputes. Rescore on the document list re-runs the collection’s intake agent over the selected — or, with nothing selected, the filtered — documents, so it re-extracts rather than merely re-scoring: use it when the agent changed, not to tidy up after a correction.
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.

Gated by what you were given. Someone with the Viewer workspace role gets a read-only summary — every field visible, nothing editable, no stage transitions. If fields will not edit, check the person’s role and personas before assuming a bug. Both are covered in Access & roles.

Four eyes for decisions that matter

For consequential decisions, one reviewer is not enough — the Four-Eyes lifecycle gives you two. L1 Review is the first human eye; L2 Approval is the second, and the gate. A new Processing collection arrives with the two reviewer personas that pattern needs — L1-Reviewer and L2-Approver — which you manage under Studio ▸ Governance ▸ Users & Access ▸ Personas.

One step is yours to take. The seeded stages start open to everyone: set each stage’s Can be viewed by — L1 Review to L1-Reviewer, L2 Approval to L2-Approver — and only then is it true that no single person can push a document from intake to approved. Two personas, two gated stages, four eyes: the four-eyes rule made structural rather than procedural.

Personas are the project’s own workflow roles — Underwriter, L1-Reviewer, L2-Approver — and each one covers the collections and stages it can work in, the people who hold it, and which other personas it may view. They are separate from the workspace roles that decide what someone can do across the platform.

One detail 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. The seeded ways back are modelled explicitly: Needs Info loops a document back through AI Processing when information arrives, and the seeded L2 Approval stage already routes back to L1 Review, so an approver can return work without an edit to the graph.

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:

Control	Starts at	Meaning
The on/off switch	Off	The master switch — it reads “Auto-decide is OFF (Four-Eyes always on)” until you flip it.
Min confidence	92%	A slider, shown as a percentage — the agent confidence a document must reach to auto-promote.
Require zero open flags	On	Any open flag on the document blocks auto-promotion.
Max amount ($)	No cap	A monetary ceiling. Set one and an Amount field name box appears for the field it reads.
Applies to	Both approve and decline	Which verdicts may auto-fire: Approve only, Decline only, or both.

The card previews the policy in plain English — “Auto-approve when AI confidence ≥ 92% AND zero open flags AND amount ≤ $500,000.” The safest opening move is to switch it on with Applies to = Approve only: 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 watching on a dashboard (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 timeline: who moved it, when, and from which stage to which. There is no separate decision record to look up: the trail is the decision, read back. The whole story is one click away: the document’s Audit trail side sheet shows that timeline, stage moves included. A reviewer’s move is also written to the project audit feed under Studio ▸ Governance ▸ Oversight ▸ Audit & Usage, attributed to them.

Watch out — an auto-decided move is not labelled as a machine. Auto-decide writes the stage change straight to the document’s timeline. Two consequences you should know before you promise an auditor anything. First, the move is stamped with the auto-decide service address, and the trail classifies any address as a person — so an auto-decision reads with a Human actor icon and files under the Human review phase rather than System. Second, the confidence that triggered it is not stored on the row: the timeline tells you the document moved from AI Recommendation to Approved, not that it cleared 94%. Auto-decided moves also bypass the project audit feed — they appear on the document timeline only. If provable machine-versus-human sign-off is a hard requirement, keep Auto-decide off until that gap closes.

When an auditor asks who approved an invoice, 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 ▸ 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 — the on/off switch, Min confidence, Require zero open flags, Max amount ($), Applies to
2	Which stages queue for a human	Each stage’s Create / Edit State dialog	Send to Inbox (human review) — the setting that makes a stage a review stage
3	Who may act at each gate	The same stage dialog	Can be viewed by, plus the L1-Reviewer / L2-Approver personas on the four-eyes stages

The personas you pick in column 3 are created on Studio ▸ Governance ▸ Users & Access ▸ Personas.

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.