LangGraph Human-in-the-Loop in Practice: How to Build a Multi-Agent Approval Workflow

What This Guide Covers

• How to prevent AI agents from accidentally invoking high-risk, irreversible, or expensive tools when operating unattended in complex workflows.
• How to pause state, allow external modifications, and resume execution without breaking the Directed Acyclic Graph (DAG) state flow.
• How to define control boundaries between Supervisors, Workers, and human nodes in multi-agent collaboration systems.
• How the system should roll back state and safely terminate or replan when a human operator rejects an AI-proposed plan.
• How to design secure data routing in concurrent multi-user environments to prevent approval threads from cross-contamination or interleaving.

Who This Guide Is For

• Backend developers who are already familiar with LangGraph basics and are attempting to apply agent systems to real-world business scenarios.
• System architects who need to integrate with internal OA, CRM, or ERP systems and have extremely high requirements for data security and operational auditability.
• Independent developers who have experienced model “hallucinations” leading to accidental invocations of send or delete tools, leaving them wary of automation.
• Developers looking to deeply understand the underlying mechanics of LangGraph state persistence, Checkpointers, and stateful graph orchestration.

1. Why Production-Grade Agents Cannot Be Fully Autonomous

Where This Article Fits in the LangGraph Series

This article specifically addresses manual approval, pause/resume functionality, and the isolation of high-risk tools. If you haven’t yet implemented state persistence, start with LangGraph Checkpointer in Practice; if your approval resumption frequently causes thread mixing, go back to thread_id, session_id, user_id Design; and if your approval nodes require retry and degradation logic after errors, review LangGraph Multi-Agent Failure Recovery.

Pre-Deployment Review Checklist

Before deploying the approval workflow, it is recommended to check off each item on the following list:

• Are high-risk tools disabled by default, requiring explicit Supervisor-triggered approval for execution?
• Is the payload returned to the frontend via interrupt properly sanitized and minimized?
• Are there clear branching logic for all four states: approved, rejected, modified, and timed out?
• Does the approval resume endpoint validate user_id + thread_id + approval_id rather than relying solely on a single token?
• Can approval records be replayed, including the original proposal, human modifications, final execution results, and the operator?

In June, Guiyang was battered by torrential rain hammering against the office windows. On my desk, the Mac Studio M2 Max whirred faintly as it ran large-scale multi-agent regression tests. I reached for my coffee when a line of logs on the screen made my blood run cold: due to the model’s overinterpretation of a user’s vague instruction, the Analysis Worker was autonomously calling the write_database tool, attempting to batch-delete historical CRM records.

During the demo phase, fully autonomous agent execution feels undeniably high-tech. But in production, granting AI unrestricted and irreversible operational permissions is a disaster waiting to happen.

High-risk actions in production environments are obvious:

• Sending commercial emails to key clients.
• Physical deletion or bulk write operations (SQL writes) on databases.
• Transfers, deductions, and invoice generation in financial systems.
• Execution of deployment scripts and service shutdowns in live production environments.
• Electronic signing of formal contracts or export of confidential information.

If these scenarios were left entirely to a large language model, a single probabilistic hallucination could result in catastrophic business losses for the enterprise. Therefore, a hard human-in-the-loop barrier must be established between reversible read-only analysis and irreversible write operations. This is the sole justification for Human-in-the-loop (HITL). It is not a concession to model limitations, but a mandatory practice in industrial-grade software engineering.

2. What Problem Does LangGraph Interrupt Solve?

In traditional workflow orchestration, implementing human approval typically requires breaking the integrity of the workflow. You often have to save the state to a temporary database, forcibly terminate the current process, and wait for manual confirmation on a backend interface. Once confirmed, you must use a new process and entry point to retrieve the data and reinitialize it. This approach is inelegant; it fragments workflow logic and makes tracking complex contexts exceptionally painful.

LangGraph’s native interrupt mechanism is designed to solve this problem elegantly. Its essence lies in allowing you to emit a suspension signal directly from any node during graph execution, halting the current Directed Acyclic Graph (DAG) run and returning a structured payload requiring human review to the caller.

At this point, the Graph pauses, but all its context, state variables, and call history do not disappear. Instead, they are safely persisted to a database via the underlying Checkpointer mechanism. When a human completes the approval or modifies relevant parameters externally, you simply send a resume signal carrying the same thread_id. The Graph then seamlessly resumes execution from the exact point of interruption, following the original topology.

This is effectively like hitting a physical pause button on an executing AI thread.

3. How Do Supervisor and Worker Roles Divide Responsibilities in Approval Flows?

In Multi-Agent Systems, the biggest pitfall in designing approval flows is when Worker agents act independently. If a MailWorker responsible for sending emails triggers an interrupt within its own Tool, it becomes difficult to manage state and leads to high system coupling.

I believe a production-grade approval architecture should follow these division-of-labor principles:

The Supervisor agent acts as the central brain, managing global task risk assessment and routing logic. Worker agents serve as specialized execution tools, responsible only for generating structured proposals (Proposed Action). They should not possess direct access to any physical write tools.

For example, when a user requests “send last month’s financial report to the client”:

• The Supervisor receives the request and calls the AnalyticsWorker to organize data and draft the email.
• The AnalyticsWorker completes its work but does not directly call the send_mail tool. Instead, it returns standard structured data declaring the drafted content along with a flag indicating that human confirmation is required.
• Upon receiving the Worker’s response, the Supervisor detects that requires_approval is true and triggers an interrupt suspension within the Supervisor’s decision node.
• After external human approval, the Supervisor decides whether to dispatch the task to specific Executor tool nodes based on the outcome (approve/reject/modify) or return it to the Worker for replanning.

We can define a strict JSON contract for the Worker’s proposal output:

{
  "action_type": "send_email",
  "risk_level": "high",
  "target": "[email protected]",
  "summary": "向客户发送 5 月份投资复利审计报告",
  "proposed_payload": {
    "subject": "5月度AltStack资产审计报告",
    "body": "您好，附件为您的 5 月度投资回报明细，请查收。"
  },
  "requires_approval": true
}

4. What Should an Approval Node Look Like?

An approval node is not merely a simple interactive popup at the underlying level; it is a data entity with a complete lifecycle, traceability, and auditability.

When defining an approval node in LangGraph, the node must expose the following structured data to external systems so that frontend pages or OA systems can correctly parse and render it:

{
  "approval_id": "appr_9x882a17f",
  "user_id": "usr_9921",
  "thread_id": "th_langgraph_hil_003",
  "run_id": "run_8b11c9f2",
  "proposed_action": {
    "tool_name": "send_email",
    "payload": "..."
  },
  "risk_level": "critical",
  "created_at": "2026-06-12T09:56:00Z",
  "approval_status": "pending"
}

On the backend, the evolution of approval status should follow a unidirectional, single-color track. Its initial state is inevitably pending; after human interaction, it branches into the following outcomes based on the action taken:

• approved: The review passes, and the data is directly dispatched to subsequent tool execution nodes.
• rejected: The review is denied, terminating the tool invocation. The rejection reason is written back to the graph state, allowing the Supervisor to decide whether to return it for rewriting or to report an error directly to the user.
• edited: The reviewer determines that the overall logic of the proposal is sound but contains minor flaws (e.g., typos in an email or an overly broad limit condition in SQL). They directly modify the data within the proposed_payload and then submit it for execution.
• expired/cancelled: The approval times out and becomes invalid, or it is manually revoked.

5. How to handle the three outcomes: approve, reject, and edit?

In LangGraph’s node logic, we need to leverage the graph’s state (State) to pass along human review feedback. Below are the core implementation mechanisms for handling these three decisions.

First, we define the global state structure for the graph. In src/types/ or directly within the definition:

from typing import TypedDict, Optional, Any

class AgentState(TypedDict):
    task: str
    proposed_action: Optional[dict]
    action_result: Optional[dict]
    approval_status: Optional[str] # approved | rejected | edited
    approval_response: Optional[Any]

When the graph execution reaches the critical approval node prep_approval_node, we trigger a graph suspension by calling interrupt.

from langgraph.errors import NodeInterrupt

def prep_approval_node(state: AgentState):
    action = state.get("proposed_action")
    if action and action.get("requires_approval"):
        # 触发硬性挂起，向调用者传递需要审核的数据包
        raise NodeInterrupt({
            "message": "请确认高危操作",
            "proposed_action": action
        })
    return {}

Externally, the graph execution is interrupted, and the API returns a pending status. This state is displayed on an external console or approval system interface. Once the approver makes a decision, we write the approval result using update_state and resume the graph execution using resume.

In the next node after resumption, execute_action_node, we must implement defensive decision logic to handle branching:

def execute_action_node(state: AgentState):
    status = state.get("approval_status")
    action = state.get("proposed_action")

    # 严格防御：无明确批准标记，绝不调用任何写工具
    if status == "approved":
        # 正常调用真实执行工具
        result = call_real_tool(action["tool_name"], action["proposed_payload"])
        return {"action_result": result, "approval_status": None}

    elif status == "edited":
        # 获取人工修改过的载荷进行执行
        edited_payload = state.get("approval_response")
        result = call_real_tool(action["tool_name"], edited_payload)
        return {"action_result": result, "approval_status": None}

    elif status == "rejected":
        # 拒绝路径，拒绝调用工具，将信息反馈给 Supervisor 重新规划
        reason = state.get("approval_response", "人工拒绝")
        return {
            "action_result": {"status": "failed", "error": f"审批未通过: {reason}"},
            "approval_status": None
        }

    else:
        # 未知状态，安全阻断并强制报错
        raise ValueError("安全策略阻断：未检测到合法的审批标记，拒绝执行高危工具。")

Through this logical design, the system achieves safe control over branch paths by updating approval_status without deconstructing the DAG structure.

6. What Role Does the Checkpointer Play in the Approval Workflow?

When discussing Human-in-the-loop (HITL) systems, many developers overlook the existence of the Checkpointer. In reality, without a reliable, persistent checkpointing system, any approval workflow would be rendered useless in a production environment.

Why is this the case? Because an interrupt only suspends the memory state of the current computation thread. If your Agent service runs in a container (such as Docker) or within a cloud Serverless architecture:

• By the time the approver opens the web interface for review, several hours may have passed.
• At that point, the original computation process may have already been physically destroyed due to timeouts or container restarts.
• Without a Checkpointer, all previous execution states, variables, and context would vanish along with the released memory.

The role of the Checkpointer is to automatically serialize the current graph state (State) and all checkpoint data generated after nodes complete their execution at the exact moment an interrupt is triggered, writing them to a physical database (such as Redis, SQLite, or PostgreSQL).

When external approval is completed and an update signal is sent, you simply specify the thread_id:

1. The system retrieves the historical snapshot from the moment of suspension from the database using the thread_id.
2. The deserialized graph state is reloaded into memory.
3. The externally written approval status is merged into the current state.
4. Execution resumes downward from the node where it was previously interrupted.

This means that the Checkpointer provides the ability to resurrect state across time, space, and physical processes. In production deployments, you should always use a stateful, persistent checkpointing mechanism.

7. How to Prevent Thread Contamination in Multi-User Approval Workflows?

If not designed carefully during development, multi-user high-concurrency scenarios are highly susceptible to severe security incidents known as “thread contamination” or “cross-wiring”: User A approves an operation, but the application applies it to User B’s thread_id, resulting in User B’s funds being mistakenly transferred or their data being accidentally deleted.

To absolutely prevent such contamination incidents, the following variables must be strictly bound and cross-validated at the architectural design level:

user_id + thread_id + run_id + approval_id

When persisting state and updating the graph, we must adhere to the following design ironclads:

• Never update global state using a generic approval_id without first validating the thread_id.
• Every proposed_action generated by an approval task must explicitly carry the current thread_id and reviewer_id.
• When writing approval results back via Webhook, the interface layer must first verify that the currently logged-in user has read/write permissions for the session associated with this thread_id through their active Session. Only after successful validation should the state_update write operation be executed.
• When saving logs, it is mandatory to write the operator’s reviewer_id and the approval timestamp into the database snapshot as irrefutable evidence for subsequent compliance audits.

8. Which Tools Must Enter Approval?

To strike a delicate balance between security and work efficiency, we cannot apply a one-size-fits-all approval strategy to all tool calls. Doing so would overwhelm reviewers with countless minor approval pop-ups, eventually reducing the approval workflow to a mere formality (reviewers will blindly click “approve”).

I believe the tool library should be divided into three risk tiers:

1. Low-Risk Tools Allowed for Automatic Execution (No Side Effects, Read-Only)

These tools typically do not alter any system state; they only perform retrieval and analysis. They can be fully open to the AI without requiring human confirmation.

• read_file (Read file)
• search_knowledge_base (Search knowledge base)
• call_weather_api (Weather query)
• text_classification (Classification)
• format_data (Formatting)

2. Medium-Risk Tools Requiring Approval (Minor Side Effects, Reversible)

These tools generate external behaviors or modify local business systems, but remain within the scope of being overridden or rolled back through subsequent actions.

• update_crm_contact (Update contact phone number)
• create_draft_article (Create article draft)
• send_internal_slack_message (Send internal notification)
• calculate_compound_interest (Complex financial value estimation and write)

3. High-Risk Tools Requiring Mandatory Approval (Irreversible, High Cost)

Once executed, these cause irreversible changes to the physical world, corporate assets, or core data. They must undergo strict verification and confirmation at the system level by a human.

• delete_database_record (Physical deletion of data)
• execute_raw_sql (Execute raw SQL statements)
• send_client_email (Directly send emails to external clients)
• transfer_funds (Financial transfers)
• publish_to_production (Deploy code or data to production)

9. Common Mistakes

When developing LangGraph human-in-the-loop approval workflows, there are several classic pitfalls that I have already stepped into for you:

Common Pitfall 1: Frontend Interception Only, Backend Tool APIs Left Exposed

This is the most common and dangerous security vulnerability. Developers merely add a frontend popup asking users to click “Confirm,” but the backend implementation of the graph does not validate the approval_status when executing the tool. It executes immediately upon receiving the model’s call instruction. If network fluctuations occur, the frontend refreshes, or someone bypasses the UI with direct API requests, the safety net instantly fails.

• Solution: At the actual Python/Node code execution layer of the Tool, a secondary assertion check must be enforced.

Common Pitfall 2: Worker Agents Directly Possess Write Tool Permissions

In some designs, the Worker node directly includes send_mail_tool in its available tools. This allows the Worker to bypass the Supervisor’s risk-control routing and self-complete the call during execution.

• Solution: Workers should only output structured Action proposals. These must be centrally handed over to a Supervisor with risk-control logic or a dedicated approval router for filtering and distribution.

Common Pitfall 3: Throwing Non-Persistent Exceptions When Triggering Interrupts

If the underlying persistence library is not properly configured during suspension, the system may fail to locate the original state snapshot after process drift or multi-pod load balancing resumes approval. This results in console output similar to the following exception log:

langgraph.errors.CheckpointNotFoundError: Checkpoint with thread_id 'th_003' and checkpoint_id 'cp_9a2f1' was not found in database.

• Solution: Ensure that when initializing the Graph in both development and production environments, you pass a persistent instance of SqliteSaver, PostgresSaver, or RedisSaver, and that the thread_id generation rule is globally unique.

10. Pre-deployment Checklist

Before merging your multi-agent approval system code and deploying it to production, perform a final physical check against the following list:

• [ Have the tools been categorized into three tiers: read-only, reversible write, and high-risk write?
• [ Have all high-risk tools implemented a hardcoded assertion for state.get("approval_status") == "approved" in their backend execution code?
• [ Is the interrupt logic bound to persistent storage (Checkpointer) and capable of state recovery across Pods?
• [ Is the thread_id strictly validated against the user session user_id to prevent privilege escalation vulnerabilities?
• [ Does the approval state machine fully cover the three workflows: approved, rejected, and manually edited?
• [ After a manual rejection, can the graph safely fall back to the Supervisor planning node or output a safe failure result, rather than getting stuck?
• [ Has an audit log table been designed in the database to record reviewer_id, approved_at, and request_payload?
• [ During concurrency testing, does triggering approvals simultaneously for multiple users cause state pollution or thread cross-contamination?

FAQ

What is the fundamental difference between LangGraph’s Human-in-the-loop and a standard frontend confirmation dialog?

A standard dialog only blocks at the interaction layer. If the user refreshes the page or the network disconnects, the state is lost, and the process can even be bypassed entirely. LangGraph’s Human-in-the-loop pushes the pause and resume capabilities down to the underlying graph state engine and Checkpoint. Even if the service restarts due to a power outage, it can perfectly recover via the thread_id. This represents a protocol-level and engine-level block.

Does the graph consume tokens while waiting after an approval suspension?

No. Once the graph execution reaches the suspension node and throws a NodeInterrupt exception, the current execution process exits safely, and the state is written to the database. The entire system ceases all computation, so it absolutely does not consume LLM tokens. Tokens are only consumed again when an external system receives the approval result and calls resume to restore execution, which relaunches the graph and continues model interactions.

In a multi-agent system, how is the payload returned after a human edit passed back to the Agent state?

When calling update_state(thread_id, values, as_node="prep_approval_node"), you can directly write the modified payload dictionary into the approval_response key of the graph’s global State. Then, during execution, the node reads this manually modified parameter from state.get("approval_response") and passes it to the actual Tool for execution.

Series Navigation

LangGraph Production-Grade Agent Orchestration in Practice Series:

• Part 1: Supervisor / Worker
• Part 2: State Isolation
• Part 3: Human-in-the-loop
• Part 4: Failure Recovery
• Part 5: Observability
• Part 6: Checkpointer
• Part 7: Subgraph

Continue Reading

• LangGraph Multi-Agent Collaboration in Practice: How to Design Supervisors, Workers, and State Handoffs
• LangGraph State Isolation in Practice: How to Design thread_id, session_id, and user_id
• CrewAI vs LangGraph: 5 Key Considerations for AI Agent Orchestration Selection
• MCP OAuth Authentication in Practice: Why Remote MCP Servers Can’t Go Unprotected
• A Practical Guide to AI: Deep Dive into LLM Development Engineering Details

Topic path / LangGraph

Continue through the production LangGraph learning path

The LangGraph hub organizes state isolation, checkpointing, human approval, retries, observability, supervisors, subgraphs and memory into one reviewable path.

Open LangGraph hub → Start with state isolation Subscribe for updates