Human-in-the-Loop
Use interrupt() to pause agent execution for human approval, collect input mid-run, and resume with Command. Covers the node restart trap, production checkpointers, and the five anti-patterns that silently break interrupts.
Quick Reference
- →interrupt(): pauses a node at runtime and surfaces a JSON-safe payload to the caller
- →Command(resume=value): injects user input into the paused node — the interrupt() call returns this value
- →Command(goto='node'): routes to a named node on resume — use for approve/reject branching
- →Node restart trap: on resume the entire node re-executes from line 1 — place side effects AFTER interrupt()
- →interrupt_before / interrupt_after: debugging breakpoints only — NOT recommended for HITL workflows
- →Production checkpointer: PostgresSaver from langgraph-checkpoint-postgres — MemorySaver is dev-only
- →LangGraph waits indefinitely for a resume — your app must cancel or timeout stale threads
When HITL Adds Value (and When It Doesn't)
HITL is not free. Every interrupt() call is a latency gate — the agent stops until a human responds, which could be seconds or hours. The infrastructure cost is real: you need a durable checkpointer, a way to surface pending interrupts to reviewers, and a timeout strategy for approvals that never arrive. Use it deliberately.
| Use HITL | Skip HITL |
|---|---|
| Irreversible: send_email, charge_payment, delete_record | Reversible reads: search, fetch, summarize |
| High-cost error: wrong vendor, wrong recipient, wrong amount | Low-stakes, low-variance: get_weather, translate_text |
| Regulatory: financial approval workflows, PII access gates | High-volume pipelines: > 100 calls/hour — human latency kills throughput |
| Data quality gate: LLM output written directly to a database | Well-tested agent with known, acceptable failure rate |
If you cannot name the specific failure mode the human catches, you do not need HITL. The overhead includes: checkpointer round-trips, thread state management, timeout handling, and a reviewer UI. None of that is free — and a poorly scoped HITL gate often becomes the bottleneck that makes the agent worse than a script.