Human-in-the-Loop

Pausing an agent for human approval, editing or input at risky points: durable interrupts, tool approval gates (approve / edit / reject), escalation triggers, reviewer UX and security, and how the major frameworks implement it.

Contents

Human-in-the-loop (HITL) means an agent stops at chosen points and waits for a person before going on. The person can approve, edit, or reject a proposed action, answer a question, or take the task over. Two things are needed to build it. The first is a policy that decides when to pause: specific tools, risky arguments, failure thresholds, or the model’s own uncertainty. The second is a durable pause, a way to save the run, release the process, and resume it minutes or days later on whichever machine is available. Without the second part, an approval gate only works while one process stays alive. That is why HITL in practice rests on durable agent execution. HITL is one layer of agent guardrails. It does not replace sandboxing or least privilege (Meta Rule of Two).

The interaction patterns

PatternWho initiatesExample
Approval gate (approve / reject)Policy on a tool callRefund, send email, git push, payment
Edit before executePolicy; reviewer changes argsFix the recipient or amount, then run
Respond / substituteReviewer answers in place of the toolHuman supplies the result directly
Ask for inputAgent asks a question“Which of these two approaches?”
Interrupt / steerHuman stops a running agentCorrect a wrong assumption mid-task
Escalation / handoffFailure threshold or risk scoreHand the case to a human agent
Review the artifactAgent finishes; human gates the mergeCopilot cloud agent PRs (see coding agents)

Sources: LangChain HITL, OpenAI HITL, Anthropic autonomy study, OpenAI practical guide, Copilot cloud agent.

How the durable pause works

flowchart TD
  A["Model proposes tool call: refund(order=42, amount=900)"] --> B{"Policy: needs approval?"}
  B -->|"no"| E["Execute tool"]
  B -->|"yes"| C["Persist state + pending call (thread_id / token)"]
  C --> D["Notify reviewer: action, args, allowed decisions"]
  D --> Z["Process exits: no compute held"]
  Z --> H["Reviewer decides: approve / edit / reject (authenticated)"]
  H --> V["Load state, validate decision against pending call"]
  V -->|"approve / edit"| E
  V -->|"reject"| F["Return rejection message to model"]
  D -.->|"deadline passes"| T["Timeout fallback: escalate or auto-reject"]
  E --> L["Loop continues"]
  F --> L

Synthesis: combines the interrupt/resume flows in the LangGraph, OpenAI Agents SDK, Workflow SDK and Restate docs.

What each framework provides:

  • LangGraph calls interrupt(value) inside a node. A checkpointer and a stable thread_id are required. The payload surfaces as __interrupt__, and invoke(Command(resume=v), config) resumes. On resume the whole node re-runs from its first line, so code before the interrupt must be idempotent. Multiple interrupts in one node are matched by order. Never wrap interrupt() in a bare try/except. interrupt_before/interrupt_after are debugging tools, not a HITL mechanism (LangGraph persistence, notebook experiment). See LangGraph.
  • LangChain HumanInTheLoopMiddleware sets interrupt_on={tool: True | False | InterruptOnConfig}. The decisions are approve, edit, reject and respond. Deny side-effecting tools with reject, because respond looks like a successful tool result to the model. Batched mode needs ordered decisions. Per-call mode (langchain>=1.4.6) keys decisions by interrupt ID. A conditional when predicate must evaluate the same on resume (LangChain HITL).
  • OpenAI Agents SDK sets needs_approval=True or an async predicate on the args. A paused run returns result.interruptions. You then call to_state(), then state.approve()/reject() (sticky via always_approve), then Runner.run(agent, state). state.to_json() / RunState.from_json() let the run wait across processes (OpenAI HITL). See OpenAI Agents SDK.
  • Claude Agent SDK checks permissions in order: hooks, deny rules, ask rules, permission mode, allow rules, and finally the canUseTool callback. Deny rules hold even in bypassPermissions. Auto-approved calls never reach canUseTool, so use a PreToolUse hook to see them. Headless deployments use an explicit allowedTools list plus dontAsk mode (permissions). See Claude Agent SDK.
  • Vercel AI SDK 7 offers tool approval policies (require, auto-approve, auto-deny, or a typed function) at the call or agent level. Optional HMAC signing binds the approved inputs to the approval token, so arguments cannot be swapped after approval. needsApproval is deprecated in favour of toolApproval. The loop stops when a tool needs approval (AI SDK 7, AI SDK docs). WorkflowAgent makes the wait durable (Vercel guide).
  • Durable engines. The Workflow SDK uses createHook({token: "approval:<id>"}) + resumeHook(), raced against sleep("7d") (Workflow SDK). Restate uses awakeables resolved over HTTP, with the timer and the promise both persisted, so the remaining wait time survives restarts (Restate). Inngest uses step.waitForEvent with match on e.g. data.invoiceId, which returns null on timeout (Inngest). In Temporal, an approval callback in Workflow context waits on a Signal or Update (Temporal integration).
  • LlamaIndex uses InputRequiredEvent/HumanResponseEvent. In web apps, snapshot the context, cancel, and restore when the answer arrives. ctx.wait_for_event() replays the code before it, so prefer separate steps (LlamaIndex). Microsoft Agent Framework offers ctx.request_info() and approval-required tools (MAF workflows).

Deciding when to pause

  • By action risk. OpenAI’s guide names high-risk actions (cancellations, large refunds, payments) and failure thresholds (too many retries, repeated misunderstanding) as triggers (OpenAI guide). Meta’s Rule of Two: when an agent combines untrusted input, sensitive data/systems, and state change or external communication in one session, it should not run autonomously. It needs HITL or another reliable check (Rule of Two; see prompt injection).
  • By argument, not just tool. Use predicates (needs_approval callable, when): for example, auto-approve refunds under a threshold and gate larger ones. Restate’s example gates claims above 1,000 USD (Restate).
  • By sandbox boundary. Codex asks before leaving the sandbox, using the network or running untrusted commands (on-request). It uses never only for CI, and only together with a sandbox. An optional reviewer agent screens requests and fails closed (Codex). See code execution sandboxes.
  • At the artifact. Copilot’s cloud agent cannot merge or approve its own PRs. The requester cannot approve their own agent PR, and Actions on agent PRs wait for a write-access user’s approval (Copilot).
  • Let the model ask. On complex tasks, Claude Code stops itself to ask more often than humans interrupt it. Its top reasons are presenting a choice (35%), gathering diagnostics (21%), and clarifying vague requests (13%) (autonomy study).

Approval fatigue and escalation UX

Per-step approval does not scale, and people stop reading what they approve. Meta notes that “blindly approved” confirmations still fail (Rule of Two). Anthropic’s Feb 2026 data shows that experienced users auto-approve more (about 20% of sessions under 50 sessions, over 40% by 750) but interrupt more (about 5% to 9% of turns). Oversight moves from approving each step to monitoring and intervening. Anthropic recommends designing for visibility and easy intervention rather than mandating approval of every action (autonomy study).

Synthesis, practical UX rules drawn from the above:

  • Show the reviewer the exact action and arguments, a diff or preview of the effect, why the agent wants it, and the allowed decisions. Escape tool names and arguments before rendering them (OpenAI HITL).
  • Offer edit, not just yes/no, and return rejection reasons to the model so it can re-plan.
  • Use sticky/scoped approvals (“always allow read_file”) for low-risk tools, so attention goes to the risky ones.
  • Every wait needs a deadline and a fallback: escalate to another reviewer, auto-reject, or route to an automated evaluator as in Restate’s example. Notify through the channel where reviewers already work (Slack, email, dashboard).
  • Record approver identity, decision, and the final arguments for audit (AI governance).

Security of the approval channel

The resume endpoint becomes the most privileged API in the system:

  • Authenticate and authorize the approver. A Workflow SDK hook token identifies the run but does not authenticate the caller. Store an approverId and check it, and verify webhook signatures (Workflow SDK, Vercel guide). See agent authentication and authorization.
  • Bind the approval to the inputs (AI SDK HMAC signing), and validate decision IDs against the server-stored pending calls (AI SDK 7, OpenAI HITL).
  • Resume atomically, once. A snapshot must not be resumable twice. Serialized state is not authenticated, so keep it server-side and load only trusted snapshots (OpenAI HITL).
  • Approval does not mean exactly-once. A tool that was approved can still be retried after a crash, so idempotency keys remain necessary (OpenAI HITL).
  • Mint tokens in a step. In replayed workflow code, random values are seeded and predictable (Workflow SDK).

Failure modes

FailureCauseFix
Side effect runs twice on resumeLangGraph re-runs the node; code before interrupt() not idempotentPut the interrupt first, or split nodes
Decisions applied to wrong callsBatched decisions out of order; non-deterministic interrupt orderPer-call mode keyed by ID
Pause silently skippedtry/except swallowing the interrupt exceptionNever catch-all around interrupts (ADK 2.0 warns of the same; see Google ADK)
Rejected action reported as successUsing respond instead of rejectreject for side-effecting tools
Approval lost on deploy/crashIn-memory saver, process-bound waitPersistent checkpointer or durable engine
Run hangs foreverNo timeout on the waitRace against durable sleep; fallback path
Forged approvalUnauthenticated resume endpointAuthn/z, signatures, input binding
Rubber-stampingToo many low-value promptsRisk-based gating, sticky approvals, monitoring

Sources: as cited above.

When to use / when not

Synthesis:

  • Use HITL for irreversible or externally visible actions (payments, outbound email, deletes, production deploys), regulated decisions, whenever the Rule-of-Two trifecta is present, and during early rollout to collect failure data for evals (OpenAI guide). Only 0.8% of sampled API tool calls looked irreversible (autonomy study), so gate that small fraction tightly rather than gating everything.
  • Prefer other controls for reversible, read-only, or sandboxed work: sandboxes, allowlists, guardrail tooling, and post-hoc review of artifacts such as PRs.
  • Avoid synchronous HITL in latency-critical paths such as voice agents. Escalate to a human handoff instead.

Sources

Suggest changes →