HITL checkpoints in pipelines - Apragya Docs

Pipelines and agents both support HITL - human-in-the-loop checkpoints - but they're different mechanisms. Agent-level HITL pauses one agent run when its own guardrail trips. Pipeline-level HITL pauses the broader pipeline run at a designated node, independent of which agent's running underneath. This guide covers the pipeline variant; see the AI Agents HITL guide for the agent-level variant.

When to use pipeline HITL

Multi-step process needs sign-off between steps - e.g., contract drafted by agent, then legal reviews, then finance reviews, then sent to counterparty
Cross-cutting business rule - approval threshold that doesn't belong to any one agent ("any pipeline that hits the ERP needs CFO sign-off above USD 100k")
Compliance gate - regulator-required human review for specific record types
Orchestration-level decision - the pipeline needs a human choice between multiple downstream branches ("refund or replacement?")

Adding a human_review node

Drag human_review from the node palette
Set the prompt for the reviewer - what they're looking at, what they're approving, what the options are
Pick the reviewer assignment: a named user, a role (the first available holder gets it), or a JSON-path expression computed from the run state ("reviewer = $.deal.owner_id")
Set the SLA - first-response deadline + escalation deadline

What the reviewer sees

Sidebar > HITL Reviews > Pending shows every paused step waiting for the current user (or for a role they hold). Each review surfaces the run state, the upstream step outputs, the configured options, and a free-text comment field. One-click approve/reject is the common case; complex reviews use the inline editor to amend the run state before resuming.

Escalation chain

If the level-1 reviewer doesn't respond by the deadline, the platform escalates to the configured level-2 reviewer (often the level-1 reviewer's manager, computed from your org chart). Up to 4 levels of escalation supported. The escalation chain is logged in audit_logs - useful for post-incident reviews of "who actually approved this".

Stuck HITL is the number-one cause of stuck pipelines. Set realistic SLAs based on your team's actual response time - 4 hours is aspirational, 24 hours is realistic, 7 days is humane. The platform sends reminders at half-time + at the deadline + at every escalation step.

Pipeline HITL vs agent HITL

Agent HITL: triggered by the agent's own guardrails (max_approval_amount, low confidence, content filter). The agent is the actor that pauses.
Pipeline HITL: triggered by an explicit human_review node in the pipeline diagram. The pipeline is the actor that pauses.
Use agent HITL for cost-aware checks tightly coupled to the agent's work; use pipeline HITL for cross-cutting business approval flows
They can compose - a pipeline can hit agent HITL inside one agent_call AND have its own pipeline HITL nodes elsewhere