TurfAI User GuideHuman-in-the-loop (HITL)
Pausing automation for a person to review, approve, or correct.
Full automation is not always the goal. For high-stakes steps — approving a settlement offer, sending an external email, releasing a payment — you want a person in the loop. HITL means a workflow can pause, wait for a human decision, and then resume exactly where it left off.
What to put behind a human
A useful rule of thumb from agent-design guidance: gate an action by its reversibility and blast radius. Let automation run freely for local, reversible steps; require a person for anything destructive, hard to undo, or visible to others.
| Risk | Examples | Default |
|---|---|---|
| Low — local, reversible | enrich a record, draft text, classify a document | Run automatically |
| Medium — externally visible | send an email, post to a channel, write to a shared system | Gate for high-stakes cases |
| High — destructive / hard to reverse | release a payment, file a claim, sign off a decision | Always require approval |
Reversibility/blast-radius framing adapted from Anthropic's Claude prompting guidance.
The pause / resume pattern
When a workflow pauses, its execution state is preserved and a correlation token is issued. Resuming the run with that token continues the execution from the paused node — the human's input becomes part of the workflow context for downstream steps.
Where HITL shows up in TurfAI
- Solution-pack squads are designed around a human handoff point — e.g. the Claims Settlement Squad produces a draft settlement offer "ready for adjuster sign-off", not an auto-sent decision.
- Execution tracking exposes paused executions and supports resume with correlation tokens (see Execution & analytics).
- The Composer asks the user to confirm before it creates a workflow, agent, or squad — a lightweight HITL on the authoring side.
Designing for HITL
Good HITL design: put the human checkpoint after the AI has done the heavy lifting (so the reviewer edits a draft, not a blank page) and before any irreversible action (sending, paying, filing). Keep the reviewer's choices simple: approve, edit-then-approve, or reject.
Some HITL surfaces are described as designed/roadmap behaviour in the source docs. Where a specific review-node configuration isn't yet documented, treat it as coming soon and model the pattern with a Decision node plus a notification step.