05 — LangGraph Human-in-the-Loop¶
A good agent knows when to stop, show its work and ask a person.
Imagine a support agent that detects a duplicate payment. It finds the transaction, calculates a proposed refund of ₹7,500 and is ready to call the payment API.
The technical question is easy: Can the agent issue the refund? The enterprise question is harder: Should it—and who is allowed to say yes?
Human-in-the-Loop (HITL) puts a deliberate decision point between an agent's proposal and a consequential action. LangGraph provides the pause-and-resume mechanics. Your application still owns reviewer identity, authorization, policy and the actual business operation.
1. Put the human at the right boundary¶
HITL is not about asking a person to approve every model response. That would turn an agent into a very expensive form-filling application.
Use human review where the impact, uncertainty or regulatory requirement justifies it:
- Low impact: search an approved knowledge base or draft an internal summary.
- Moderate impact: update a reversible customer preference, perhaps with sampling or policy checks.
- High impact: issue a refund, change account ownership, delete data or send a sensitive external communication.
A review does not always mean a binary yes/no. A person may approve, reject, edit a draft, correct extracted data, provide missing information or escalate the case to a specialist. The graph should represent the outcomes the business process actually needs.
The key boundary is between proposing and doing:
flowchart TD
A[Customer request] --> B[Agent gathers facts]
B --> C[Prepare proposed action]
C --> D[Deterministic policy checks]
D --> E{Approval required?}
E -->|No, policy permits| F[Revalidate]
E -->|Yes| G[Pause for human review]
G --> H{Decision}
H -->|Approve| F
H -->|Reject| I[Stop or escalate]
H -->|Modify| J[Validate revised proposal]
J --> K[Bind approval to revised action]
K --> F
F --> L[Execute once]
L --> M[Record outcome] A useful rule: the agent may prepare the refund; an authorized business process decides whether it can be issued.
2. Separate the responsibilities¶
Three actors have different jobs. Do not blur them just because they appear in one graph.
| Actor | Responsibility |
|---|---|
| Agent | Gather evidence, interpret the request and prepare a proposal |
| Human reviewer | Approve, reject, edit, clarify or escalate within their role |
| Application and policy services | Authenticate, authorize, validate, enforce limits and execute |
Approval is not authorization. A click on Approve does not prove that the person has permission to approve this refund, nor that the refund is still valid. The application must verify identity, role, tenant and action scope independently of the model.
Human input is untrusted input. Validate its schema and business meaning just as you would validate a request received from an external API.
3. Model the decision explicitly¶
Keep the proposal and the review outcome in graph state. For a refund workflow, that might look like this:
from typing import Literal, TypedDict
class RefundState(TypedDict):
request_id: str
proposed_amount: int # smallest currency unit, e.g. paise
approved_amount: int
decision: Literal["pending", "approved", "modified", "rejected", "invalid"]
reviewer_id: str
validation_error: str
Store only what the graph needs to continue. Avoid putting unnecessary customer secrets or full payment credentials into checkpoints. Apply the same access, encryption and retention controls to persisted graph state as you would to other sensitive application data.
4. Pause and resume with LangGraph¶
The mechanics are straightforward:
- Compile the graph with a checkpointer.
- Give the run a stable
thread_id. - Call
interrupt()in the review node with the information the reviewer needs. - The application presents that request in its review interface.
- After authenticating and authorizing the reviewer, the application resumes the same thread with
Command(resume=...).
Here is a compact Python example. The payment integration is deliberately left as a stub; the important part is the control flow.
from typing import Literal, TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import interrupt, Command
from langgraph.checkpoint.memory import InMemorySaver
class RefundState(TypedDict):
request_id: str
proposed_amount: int
approved_amount: int
decision: str
reviewer_id: str
validation_error: str
def review(state: RefundState):
# No external side effects before interrupt().
response = interrupt({
"request_id": state["request_id"],
"proposed_amount": state["proposed_amount"],
"question": "Approve, reject or modify this refund?"
})
# The review API must authenticate the reviewer first and
# construct this resume payload server-side.
if not isinstance(response, dict):
return {"decision": "invalid", "reviewer_id": ""}
decision = response.get("decision")
if decision not in {"approved", "modified", "rejected"}:
decision = "invalid"
amount = response.get("amount", state["proposed_amount"])
return {
"decision": decision,
"reviewer_id": response.get("reviewer_id", ""),
"approved_amount": amount,
}
def route_review(state: RefundState) -> str:
if state["decision"] == "rejected":
return "reject"
if state["decision"] in {"approved", "modified"} and state["reviewer_id"]:
return "validate"
return "needs_attention"
def validate(state: RefundState):
amount = state["approved_amount"]
if type(amount) is not int or not (1 <= amount <= state["proposed_amount"]):
return {"validation_error": "Amount is outside the permitted range"}
return {"validation_error": ""}
def route_validation(state: RefundState) -> str:
return "execute" if not state["validation_error"] else "needs_attention"
def execute(state: RefundState):
# Re-fetch current transaction and policy; verify approval binding.
# Call payment provider with a stable idempotency key.
return {}
def stop(state: RefundState):
return {}
builder = StateGraph(RefundState)
builder.add_node("review", review)
builder.add_node("validate", validate)
builder.add_node("execute", execute)
builder.add_node("reject", stop)
builder.add_node("needs_attention", stop)
builder.add_edge(START, "review")
builder.add_conditional_edges("review", route_review, {
"validate": "validate", "reject": "reject",
"needs_attention": "needs_attention"
})
builder.add_conditional_edges("validate", route_validation, {
"execute": "execute", "needs_attention": "needs_attention"
})
builder.add_edge("execute", END)
builder.add_edge("reject", END)
builder.add_edge("needs_attention", END)
app = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "refund-1042"}}
# First invocation pauses at interrupt().
app.invoke({
"request_id": "refund-1042", "proposed_amount": 7500,
"approved_amount": 7500, "decision": "pending",
"reviewer_id": "", "validation_error": ""
}, config=config)
# In production, the authenticated review service constructs this payload.
resume_payload = {
"decision": "approved", "reviewer_id": "reviewer-17"
}
app.invoke(Command(resume=resume_payload), config=config)
InMemorySaver is useful for a local example, not a durable multi-instance deployment. Use a persistent checkpointer suitable for your environment. The execute, reject and needs_attention functions are intentionally minimal; production code must persist outcomes and return meaningful status.
A subtle but important detail: when an interrupted node resumes, LangGraph re-runs that node from its beginning. Code before interrupt() can run again. Do not send an email, charge a card or mutate a database before the interrupt and assume it will run only once. Put consequential side effects in a later node.
5. Make approval safe after the pause¶
A reviewer may respond minutes or days later. In the meantime, the transaction may change, the approval may expire or the reviewer may lose access. Treat the decision as permission to attempt an action—not as a guarantee that the action is still valid.
Before execution:
- Authenticate and authorize: derive reviewer identity from the trusted application session, not from model output or a client-supplied name.
- Bind the decision: attach approval to the exact proposal ID/version and, for sensitive actions, a canonical action hash. A changed proposal needs a new decision.
- Revalidate: fetch current business data and re-run policy checks immediately before the side effect.
- Validate modifications: check amount limits, account ownership, currency and any business constraints deterministically.
- Prevent duplicates: use an idempotency key at the external service. A retried graph run must not issue the refund twice.
- Handle silence: define expiry, reassignment, escalation or safe cancellation. A timeout must never silently become approval.
- Audit: record the proposal, reviewer, decision, timestamp, policy result and execution outcome.
sequenceDiagram
participant G as LangGraph
participant C as Checkpointer
participant A as Review API
participant H as Reviewer
participant P as Policy and payment service
G->>C: Save state at interrupt
G-->>A: Surface review request
A->>H: Display proposal and evidence
H->>A: Approve / reject / modify
A->>A: Authenticate and authorize reviewer
A->>G: Resume same thread with trusted decision
G->>P: Revalidate proposal and policy
P-->>G: Authorized result
G->>P: Execute with idempotency key
G->>C: Persist final outcome The review queue, notifications, reviewer assignment and user interface are application responsibilities—not features that appear automatically when you add interrupt(). LangGraph coordinates the workflow; your application supplies the surrounding operational controls.
For sensitive operations, route reviews using least-privilege roles and tenant boundaries. High-value actions may need multiple approvals or separation of duties—for example, the person who creates a payment must not be the only person who approves it. Define review SLAs and escalation paths, then monitor queue depth, oldest pending item, turnaround time, rejection/edit rates and execution failures. A high approval rate is not automatically success: it may indicate clear proposals, or it may indicate reviewer fatigue and rubber-stamping. Human corrections can also become useful evaluation data, provided they are reviewed and labeled before being used to improve the system.
6. Choose the right oversight model¶
| Pattern | What it means | Example |
|---|---|---|
| Human-in-the-loop | Workflow pauses until a person acts | Approve a high-value refund |
| Human-on-the-loop | Workflow runs while a person monitors and can intervene | Monitor automated low-risk case handling |
| Human-out-of-the-loop | No routine human intervention | Approved read-only retrieval task |
Use deterministic policy rules for hard limits. A model-generated risk score can help prioritize review, but it should not be the authority that grants permission to perform a regulated or irreversible action.
Production checklist¶
- [ ] Pause before the consequential side effect.
- [ ] Use a stable thread ID and durable checkpointer.
- [ ] Authenticate reviewers outside the LLM.
- [ ] Validate every decision and every modification.
- [ ] Bind approval to the exact action/version.
- [ ] Revalidate current state and policy before execution.
- [ ] Make external actions idempotent.
- [ ] Define timeout, reassignment and escalation behaviour.
- [ ] Audit decisions and outcomes; monitor queue depth and review latency.
Key takeaways¶
HITL is a control boundary, not a confirmation button. LangGraph gives you the interrupt, checkpoint and resume mechanism. Your application must make the decision trustworthy. The safest pattern is simple: prepare, pause, authenticate, validate, re-check, then execute.
Practical exercise¶
Extend the refund workflow to support approval, rejection and modification. Add a maximum-refund policy, reviewer-role checks, approval expiry and an idempotency key. Test a restart while waiting, a modified amount above the limit, an unauthorized reviewer and a duplicate resume request. For each test, prove that no unauthorized or duplicate payment is issued.
Interview questions¶
- How do
interrupt(), a checkpointer andCommand(resume=...)work together? - Why can code before
interrupt()execute again after resumption? - Why is approval different from authorization?
- How do you prevent stale and duplicate approvals?
- Which parts of an HITL workflow belong to LangGraph, and which belong to the application?
References¶
🧭 Chapter Navigation¶
⬅️ Previous: 04. LangGraph Nodes, Edges and Routing
📚 Part VIII Index: AI Engineering Frameworks & Tooling
➡️ Next: 06. LangGraph Tool Execution
Enterprise AI Engineering Handbook
Building Production-Grade Enterprise AI Systems — One Chapter at a Time.