LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

NNathaniel bigo··原創首發·AI 輔助撰寫
8 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

  1. 新版官方首選方案是在節點函數內部調用 interrupt(待審數據),配合 Command(resume=人工結果) 恢復運行,比早期靜態寫死 interrupt_before 靈活得多。
  2. 暫停期間不佔後台算力:一旦撞上 interrupt(),進程直接儲存狀態並正常返回響應;哪怕主管三天後才在網頁點同意,只要帶上原 thread_id 就能原地喚醒。
  3. 少了這兩樣必定報錯:編譯圖時必須傳 checkpointer(儲存器),且每次調用必須傳 config={"configurable": {"thread_id": "..."}}。
  4. 最重要的一條底層鐵律:恢復時被暫停的節點會從該函數的第一行重新執行(只是這次遇到 interrupt() 不再停住,而是直接吐出人工傳入的 resume 值)——所以發請求、扣款等副作用代碼絕不能寫在同一個節點裏 interrupt() 的上方。

LangGraph 人工審批暫停與恢復四步

圖:本站根據 LangGraph 官方文檔 Human-in-the-loop 整理的示意圖

本文根據 LangChain / LangGraph 官方文檔《Human-in-the-loop》《Interrupts》整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 LangChain 官方網站。

適用於誰

  • 搜「langgraph human in the loop」「langgraph interrupt 用法」「langgraph 人工審批」的開發者;
  • 智能體已經能調寫庫、發電郵或退款工具了,但上線前安全團隊要求「凡是寫操作必須先暫停給主管點確認按鈕,同意後才能真執行」的後端工程師;
  • 照着文檔寫了 interrupt(),恢復時卻發現節點上半截的邏輯又重複跑了一遍、正在查原因的人。

如果你是第一次接觸狀態圖,建議先花五分鐘讀完 /guides/langgraph-quickstart-install-first-graph;為什麼這類跨天審批場景適合用圖編排,也可回顧 /guides/claude-agent-sdk-vs-langchain-how-to-choose。

一、完整可運行示例:高危操作執行前暫停等人工確認

下面的純 Python 腳本模擬了一個「執行工單補償發放」節點:當補償積分超過免審線時,調用 interrupt() 把待審詳情拋給外部調用方;等拿到人類返回的 "approve" 或修改後的數值後,再真正落庫完成。

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

class TicketState(TypedDict):
    user_id: str
    points: int
    status: str

def issue_compensation_node(state: TicketState):
    pts = state["points"]
    # 超過 500 積分時觸發動態人工掛起,把待審摘要拋出去
    if pts > 500:
        decision = interrupt({
            "question": "積分補償超免審線,請確認是否批准或修改額度",
            "user_id": state["user_id"],
            "proposed_points": pts,
        })
        if not decision.get("approved"):
            return {"status": "人工已駁回該筆發放"}
        # 允許審批人順手改小發放數值後再放行
        pts = decision.get("final_points", pts)

    # 注意:真正落庫發積分的寫操作必須放在 interrupt 之後
    return {
        "points": pts,
        "status": f"已向用戶 {state['user_id']} 成功發放 {pts} 積分",
    }

builder = StateGraph(TicketState)
builder.add_node("issue_compensation", issue_compensation_node)
builder.add_edge(START, "issue_compensation")
builder.add_edge("issue_compensation", END)

# 必須掛載檢查點儲存器(生產環境換成 PostgresSaver)
graph = builder.compile(checkpointer=InMemorySaver())

if __name__ == "__main__":
    cfg = {"configurable": {"thread_id": "ticket-9001"}}

    # 第一次調用:跑到 interrupt 處自動停住並返回 __interrupt__ 提示
    first_out = graph.invoke(
        {"user_id": "U_88", "points": 1200, "status": "pending"},
        config=cfg,
    )
    print("首次返回(已掛起):", first_out["__interrupt__"])

    # 模擬後台主管審批同意並將額度調整為 800 後恢復同一個 thread_id
    final_out = graph.invoke(
        Command(resume={"approved": True, "final_points": 800}),
        config=cfg,
    )
    print("恢復後最終結果:", final_out["status"])

運行這段代碼,你會看到第一次 invoke 並沒有執行下方的發放邏輯,而是返回了一個包含 __interrupt__ 列表的字典——你的前端頁面只需讀取裏面的 question 和 proposed_points 渲染成審批彈窗;等主管點擊按鈕後,後端接口調用第二次 graph.invoke(Command(resume=...), config=cfg) 即可跑完剩餘流程。

使用 interrupt 必防的三個踩坑點

圖:本站根據 LangGraph 官方文檔 Interrupts 規範 整理的示意圖

二、生產環境寫 interrupt 必守的三條工程紀律

  1. 把耗時大模型調用拆到前一個獨立節點:因為恢復時當前節點會從頭重跑一遍,如果你把「調大模型想方案」和「interrupt() 等人工點同意」塞在同一個函數里,點同意恢復時那次大模型調用又會被白跑一次浪費額度。正確拆法是:節點 A 調大模型生成待審參數寫入 State → 節點 B 專職調 interrupt() 拿審批結果並執行工具;
  2. 生產庫務必替換掉 InMemorySaver:人工審批往往間隔幾十分鐘甚至跨天,內存儲存器遇到服務發版重啟就會丟掉掛起線程,上線前請換成 PostgreSQL 等持久化儲存器;
  3. 配合遠程 MCP 高危寫工具一起用:當你通過適配器掛載了外部業務系統的增刪改 MCP 工具(見 /guides/langgraph-mcp-integration-guide)時,不要把刪除或群發工具裸露在全自動 ToolNode 裏,給高危工具外包一層帶 interrupt() 的人工確認殼最穩妥。開發期想直觀模擬斷點恢復,也可以直接在本地 Studio 畫布裏點按鈕測試(見 /guides/langgraph-debug-visualize-studio-guide)。

平時研發團隊藉助 Claude 或 ChatGPT 梳理複雜審批狀態轉移邊界與編寫異步回調接口時,個人官方訂閱說明也可參考 /chongzhi/claude-pro。

常見問題

Q:如果用戶掛起後一直不點審批,怎麼查詢這個 thread_id 當前是不是正卡在等待人工狀態?

隨時調用 state_snapshot = graph.get_state(cfg) 檢查返回的快照對象:如果裏面的 tasks 包含未處理的 interrupts(或 next 非空),就說明該會話當前正停在人工斷點處,前端刷新頁面時靠這個接口就能重新渲染出剛才的待辦卡片。

Q:舊項目裏用的 compile(interrupt_before=["tools"]) 還能繼續用嗎?

依然兼容保留。如果你的需求非常簡單——只要每次進工具節點前無腦一刀切停住,靜態 interrupt_before 寫起來很省事;但只要你需要「小額免審、大額才停」這類按業務字段動態判斷是否掛起的邏輯,函數內的 interrupt() 清晰得多。

相關教學

參考資料

  • LangChain / LangGraph 官方文檔:Human-in-the-loop & Interrupts — https://docs.langchain.com/
  • langchain-ai/langgraph 官方 GitHub 倉庫 — https://github.com/langchain-ai/langgraph

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  4. 04

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  5. 05

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0
  6. 06

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  2. 02

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  3. 03

    A2A 協議是什麼、怎麼用:Agent2Agent 智能體互聯規範、名片發現與 Python 接入流程

    A2A(Agent2Agent)是由 Google 發起並移交 Linux 基金會託管的開放智能體通信協議,用來讓不同團隊、不同框架開發的獨立智能體跨網絡互相派單協作。本文按官方規範講清 Agent Card、Task 狀態機與 Python SDK 接入步驟。

    Gemini其他 AI 工具0
  4. 04

    AutoGen 現在怎麼樣了?微軟官方演進路線與 Microsoft Agent Framework 入門

    搜 AutoGen 新教學常被 0.2、0.4、社區分支和 Semantic Kernel 繞暈。按微軟官方文檔,微軟已將 AutoGen 與 Semantic Kernel 兩支團隊合併推出統一的開源框架 Microsoft Agent Framework。本文講清現狀與 Python 快速上手。

    ChatGPT其他 AI 工具0
  5. 05

    CrewAI 多輪對話與記憶怎麼配:memory=True 三層記憶、人工介入與 Flows 狀態持久化

    剛用上 CrewAI 的人常疑惑 kickoff 跑完就結束,怎麼做多輪連續對話與跨次記憶。本文按官方文檔拆解 memory=True 的短期/長期/實體三層記憶、嵌入模型配置,以及用 Flows 狀態流和 @persist 搭建多輪會話的實戰寫法。

    其他 AI 工具0
  6. 06

    CrewAI 入門教學:Agent 角色、Task 任務、執行流程(Process)與第一個團隊示例

    CrewAI 是主打「擬人化角色分工」的 Python 多智能體開源框架。本文按官方文檔講清安裝要求、Agent(角色/目標/背景)、Task(任務描述與預期輸出)和 Process(順序接力與經理層級模式)的配合邏輯,並給出最小可運行代碼。

    其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~