Builds human-in-the-loop (HITL) Airflow workflows - approval gates, form input, and human-driven branching. Use when a DAG needs a human in the loop - an approval or reject step, sign-off before a task runs, a decision or approval UI, branching on a human choice, or collecting form input mid-run; al

Airflow Human in the Loop Operators Pause a DAG until a human responds via the Airflow UI or REST API. HITL operators are deferrable — they release their worker slot while waiting. Requires Airflow 3.1+ ( af config version ). UI location : Browse → Required Actions. Respond from the task instance page's Required Actions tab. Cross references : migrating ai sdk to common ai for AI/LLM task decorators; airflow for registry and API discovery commands used below. Step 1 — Pick the capability you need Capability Class (verify in Step 2) Approve or reject; downstream skips on reject ApprovalOperator Present N options and return which were chosen HITLOperator Branch to one or more downstream tasks based on a choice HITLBranchOperator Collect a form (no approve/select step) HITLEntryOperator Use the HITL trigger directly (advanced / custom operators) HITLTrigger This is the only place class names are hardcoded. The provider adds, renames, and removes params across releases — do not copy parameter lists from memory. Fetch the current signature before writing code. Step 2 — Discover the current signatures from the Airflow Registry Before writing HITL code, run these to see the live roster and constructor params (see the airflow skill for the full af registry reference): If the registry shows a param that this skill does not mention, prefer the registry. If the registry shows a class that is not in Step 1, treat it as additive — the decision table above may be stale. Step 3 — Canonical example (approval gate) Starting point for any HITL task. Adapt by swapping the class name and params per Step 2. For the other classes in Step 1, the shape is the same ( task id , subject , plus class specific params). Verify each constructor through Step 2 — for example, HITLBranchOperator requires every option either to match a downstream task id directly or to be resolved via a mapping param surfaced in the registry. Step 4 — Behavior contracts (stable across versions) Timeout With defaults set: task succeeds on timeout, default option(s) selected. Without defaults : task fails on timeout. Markdown + Jinja in body body supports Markdown and is Jinja templatable. Render XCom context directly: Callbacks All HITL operators accept the standard Airflow callback kwargs ( on success callback , on failure callback , etc.). Notifiers HITL operators accept a notifiers list. Inside a notifier's notify(context) method, build a link to the pending task with HITLOperator.generate link to ui from context(context, base url=...) . Restricting who can respond The parameter name and accepted identifier format depend on the active auth manager. Do not hardcode — check which one is active and which kwarg the current provider exposes: Then look up the current kwarg in Step 2 (at the time of writing it is assigned users , accepting identifiers in whatever format the active auth manager uses — Astro uses the Astro user ID, FabAuthManager uses email, SimpleAuthManager uses username). Step 5 — Responding from external integrations For Slack bots, custom apps, or scripts. Discover the live endpoint rather than hardcoding a path: The PATCH to respond pattern is stable; the exact path is discovered. Typical shape: Step 6 — Safety checks [ ] Airflow version ≥ 3.1 ( af config version ). [ ] Constructor kwargs match the current registry output from Step 2 — no respondents vs assigned users style drift. [ ] For branching: every option resolves to a downstream task id (directly or via the mapping kwarg from Step 2). [ ] Every value in defaults is also in options . [ ] execution timeout set; defaults configured if timeout should succeed rather than fail. [ ] API token configured if external responders are part of the flow. References The upstream docs URL is surfaced per module by the registry — do not hardcode: Related skills airflow — af registry , af api , af config command reference. migrating ai sdk to common ai — AI/LLM task decorators and GenAI patterns (common ai provider). authoring dags — general DAG writing best practices. testing dags — iterative test → debug → fix cycles.

airflow-hitl