Download all docs

Recipe: Human-in-the-Loop Approval

This recipe pauses a workflow for a human decision before it does something consequential. An automation runs up to a gate, a hitl step collects a real person’s approval, and only on approval does the following action element run. It is the safety interlock for anything you do not want fully autonomous.

The problem it solves

Some steps should never run without a human saying yes — issuing a refund, sending a contract, deleting records, deploying. A fully automated flow either does them blindly or stops being automated at all. This recipe gives you the middle path: everything around the decision is automated, and the decision itself is a clean, audited checkpoint with a real reviewer.

Elements

ElementRole
automationOrchestrates the flow and routes on the approval outcome.
hitlCollects structured human input — the approve/reject gate.
python (or any action)The consequential step that runs only after approval.

Flow

  1. Build your automation up to the point where a decision is needed.
  2. Add a hitl step. Submit the request for review with its invoke operation (the protocol alias of submit); it requires an audience (set on spec.audience or passed in the input — submitting without one returns a 400 HITL_NO_AUDIENCE). The run now waits on a human.
  3. The reviewer acts: approve (the run transitions to completed with approval status, with an optional reason for the audit trail) or reject. You can list everything currently waiting with pending, which returns audience, quorum progress, and per-respondent link URLs.
  4. Branch on the outcome in the automation. Use a condition child to run the next step on approve and skip (or escalate) on reject.
  5. Run the consequential work only on the approved branch — a python (or any action) step that performs the refund, the send, the delete.

What this shows

The human checkpoint is a first-class element, not a hardcoded pause: hitl carries an audience, a quorum, per-respondent links, and an approve/reject audit trail with reasons. The automation treats the decision like any other step — it references hitl, waits on its outcome, and routes with a condition — so the approval logic is visible in the flow graph rather than buried in code. You get autonomy everywhere it is safe and a real signature exactly where it matters.

Next pages