Human-in-the-Loop Approvals and Interrupts

Pause an agent before risky actions, collect approval or edits from a person, and resume safely with an audit trail.

Est. 30 min Updated Suggest a fix
// Part 01 — Why pause?

Let the Agent Prepare; Let a Person Decide

Agents can gather evidence and prepare a proposed action, but some decisions deserve a person's judgment. An assistant might prepare a refund request, draft a customer message, or propose a change to an account. Before a sensitive or consequential action, it can pause, show the person the proposed action and relevant evidence, and wait for an explicit decision. This is a control boundary, not a way to make the model more confident.

Human-in-the-loop (HITL) may mean approval, rejection, editing, clarification, or escalation. Choose the specific decision the person is being asked to make. Do not frame a vague "continue?" button as informed approval if the person cannot see the target, scope, and consequence of the action.

InteractionWhat the person doesExample
ApprovalApprove or reject a specific proposed operationApprove a refund request after reviewing order evidence
EditChange a bounded field before executionCorrect a draft reply or adjust a proposed date
ClarificationSupply information the system lacksConfirm which order the request refers to
EscalationTake over a decision outside the agent scopeRoute a disputed payment to a support specialist
💡 Note
An interrupt pauses graph execution. The application still has to authenticate the reviewer, display context, record the decision, and ensure the resumed run is the one that reviewer was allowed to control.
// Part 02 — Approval design

Make the Review Request Specific

Present a concise action summary, the affected account or record, the reason, source evidence, and the decision choices. For an edit, show exactly which field may change and validate the edited value before resuming. Provide reject and cancel paths, and tell the requester when the task is waiting. The reviewer should be able to inspect enough evidence without exposing unrelated customer data.

  1. Build a proposal from validated application state, not free-form model text alone.
  2. Show who or what is affected, the action, its amount or scope, and the evidence used.
  3. Collect an authenticated decision with an explicit approve, reject, or edit choice.
  4. Revalidate permissions and business rules at execution time, then record the outcome.
⚠️ Important
Approval is not a permanent permission token. Check that the proposal has not changed, expired, or been applied already before executing it, and reject stale approvals.
// Part 03 — LangGraph interrupt

Pause a Graph and Resume With a Decision

LangGraph provides interrupt() for pausing a node and Command(resume=...) for supplying a resume value. Compile the graph with a checkpointer and pass a stable, application-controlled thread ID so the paused state can be found again. The interrupt payload is information for the application to display; do not treat a value returned from the browser as trusted until the server authenticates and validates it.

approval_graph.py
python
from typing import TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import END, START, StateGraph
from langgraph.types import Command, interrupt

class RefundState(TypedDict, total=False):
    order_id: str
    amount_paise: int
    decision: dict
    result: str


def approval_gate(state: RefundState) -> dict:
    decision = interrupt({
        "kind": "refund_approval",
        "order_id": state["order_id"],
        "amount_paise": state["amount_paise"],
        "question": "Approve this refund proposal?",
    })
    return {"decision": decision}


def apply_decision(state: RefundState) -> dict[str, str]:
    decision = state["decision"]
    if decision.get("approved") is not True:
        return {"result": "Rejected; no refund was issued."}
    # Replace with an idempotent, permission-checked payment service call.
    return {"result": "Approved proposal is ready for the authorised refund service."}


def route_after_review(state: RefundState) -> str:
    return "apply" if state["decision"].get("approved") is True else "stop"


def stop(state: RefundState) -> dict[str, str]:
    return {"result": "Rejected; no refund was issued."}


builder = StateGraph(RefundState)
builder.add_node("approval", approval_gate)
builder.add_node("apply", apply_decision)
builder.add_node("stop", stop)
builder.add_edge(START, "approval")
builder.add_conditional_edges("approval", route_after_review, {"apply": "apply", "stop": "stop"})
builder.add_edge("apply", END)
builder.add_edge("stop", END)
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "refund-run-104"}}

paused = graph.invoke({"order_id": "A104", "amount_paise": 25000}, config)
print(paused["__interrupt__"])
# The server resumes only after authenticating the reviewer and validating this decision.
finished = graph.invoke(Command(resume={"approved": False}), config)
print(finished["result"])

Run the sample in an environment with LangGraph installed. The first call stops at the interrupt; the second sends a rejection to the same thread, so the state routes to the no-action branch. The approval example deliberately does not issue money: a real payment integration must verify current ownership and limits, use an idempotency key, and record the service result. In-memory checkpointing is for demonstration, not durable production recovery.

// Part 04 — Resume safely

Bind the Decision to the Exact Proposal

Resuming with Command(resume=...) is a continuation mechanism, not a complete approval system. Your backend should bind the reviewer, run ID, proposed action, and decision in a durable record. Before resuming, verify that the reviewer has authority for that action and that the proposal hash or version still matches what they saw. Reject duplicate submissions and stale decisions. An approval from one customer or one refund must not be reusable for another.

validate_approval.py
python
from dataclasses import dataclass

@dataclass(frozen=True)
class Approval:
    run_id: str
    proposal_id: str
    reviewer_id: str
    approved: bool
    proposal_version: int


def validate_resume(
    approval: Approval,
    expected_run_id: str,
    expected_proposal_id: str,
    expected_version: int,
    reviewer_can_approve: bool,
) -> dict[str, bool]:
    if approval.run_id != expected_run_id:
        raise ValueError("Approval belongs to another run")
    if approval.proposal_id != expected_proposal_id:
        raise ValueError("Approval belongs to another proposal")
    if approval.proposal_version != expected_version:
        raise ValueError("Proposal changed after review")
    if not reviewer_can_approve:
        raise PermissionError("Reviewer is not authorised")
    return {"approved": approval.approved}

In a service, load the proposal and reviewer permissions from trusted storage, not from fields submitted by the browser. The approval decision should be recorded before or atomically with the resume request so a network retry cannot silently lose the audit record. Use an idempotent resume handler and a unique decision identifier.

// Part 05 — Interrupt safety

Keep Work Before the Pause Idempotent

When an interrupted node resumes, the node may run again from its beginning before it reaches the interrupt. Do not place an irreversible side effect before the pause and assume the code after it is the only part that can run again. Prepare a proposal, persist it safely, interrupt, and perform the action only after the decision has been validated. Make the action idempotent so an at-least-once delivery or retry cannot issue it twice.

Keep the proposal immutable while it awaits review. If the order changes, the requester withdraws the request, or the approval window expires, invalidate it and ask for review again. Show the reviewer what will happen, not only the model's explanation. Maintain a cancellation path and a human escalation route for ambiguous outcomes.

🎯 Pro Tip
Separate "approved" from "completed." A human can approve a proposal while the payment service later fails; the run should report the real operation result rather than treating approval as proof of execution.
// Part 06 — Product flow

Design the Waiting Experience

A paused graph may wait seconds or hours. The product should tell the requester what is pending, who can review it, and what happens if no one responds. The reviewer needs a secure inbox, enough context to decide, and an audit history. When a decision arrives, the backend locates the correct checkpoint, validates the decision, resumes the graph, and reports the result to the original requester.

Run stateUser-facing behaviorBackend responsibility
Waiting for approvalShow pending and expected next stepKeep proposal and checkpoint linked
ApprovedShow that execution is starting or completeRecheck limits, permissions, and idempotency
RejectedExplain no action was takenPersist reviewer, reason if supplied, and timestamp
Expired or withdrawnAsk to create a fresh proposalInvalidate old resume token and proposal version
Execution failedShow failure and support routeRecord actual service outcome; do not mark complete

Escalate when the evidence is incomplete, the requested action exceeds a reviewer's authority, or the action cannot be safely reversed. A simple approve/reject control is not enough if policy requires a specialist, dual control, or an additional verification step.

// Part 07 — Audit and operations

Record the Decision Without Over-Logging

An audit trail should identify the run and proposal, the reviewer, the action version, the decision, the time, and the eventual execution result. It should make clear which service performed the action. Store only the evidence needed to support review and operations, protect the record with access controls, and apply a retention policy. Avoid logging full chat transcripts or payment credentials as a shortcut.

  1. Test approval, rejection, edit validation, expiry, cancellation, and duplicate decision submission.
  2. Verify that a changed proposal cannot reuse an old approval.
  3. Simulate a crash after the decision is saved and before the resume response reaches the caller.
  4. Confirm that the action runs once and that its final status matches the external service result.
📌 Real World Example
A customer-support agent may draft a ₹250 refund proposal from order facts. A reviewer sees the amount and evidence, then approves or rejects. The payment system remains authoritative for whether the refund actually succeeded.
// Part 08 — Pitfalls

Common Mistakes

Trusting an approval value sent directly by a browser

Why: A caller could alter the run ID, proposal, reviewer, or choice.

Fix: Authenticate on the server, load the proposal from trusted storage, verify authority, then resume.

Performing the action before interrupting

Why: The node can be re-entered during resume or retry.

Fix: Pause before side effects, persist an immutable proposal, and make execution idempotent.

Treating approval as successful execution

Why: The downstream service can reject or time out after approval.

Fix: Track approval and execution as separate states, and display the actual service result.

Reusing an approval after the proposal changes

Why: The reviewer did not consent to the new target, amount, or scope.

Fix: Bind approval to the proposal ID and version; invalidate and request review again on change.

// Part 09 — Practice

Add a Refund Approval Gate

Practice

Pause, review, validate, and resume

  1. Run the LangGraph example and inspect the interrupt payload before resuming with a rejection.
  2. Add a separate approval decision and verify only the approved branch reaches the mock action node.
  3. Bind the decision to a run ID and proposal version; reject a decision for a different version.
  4. Add an expiry or withdrawal state and prove an old approval cannot resume that proposal.
  5. Simulate a retry after the mock service succeeds and verify the idempotency key prevents a duplicate action.

Hint: Keep the action mocked. In a real application, use authenticated server-side reviewer identity and a durable checkpointer and audit store.

🎯 Key Takeaways

  • ✓Pause before consequential actions and show a person the exact proposal, scope, and evidence they are deciding on.
  • ✓LangGraph interrupt() pauses a node; Command(resume=...) supplies the continuation value to the checkpointed thread.
  • ✓An interrupt is not an approval system: authenticate reviewers, validate the proposal and authority, and bind decisions to a run and version.
  • ✓Keep side effects after the pause, re-check current rules, and make writes idempotent.
  • ✓Track waiting, approval, rejection, expiry, and external execution as distinct states.
  • ✓Maintain an access-controlled audit trail with the decision and actual outcome, not unnecessary private transcripts.

Next

What comes next

Your workflow can now pause for a person. Next, explore a standard way for agents to discover and use external tools and data.

Lesson 06 · Model Context Protocol (MCP) — Connecting Agents to Tools and Data →

HELP US IMPROVE

How was this lesson?

Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.

Choose your feedback

Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.

Share

Discussion

0

Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.

Continue with GitHub
Loading...