指南OneMux

打造具備隱私保護、工具核准與復原機制的 LangGraph Agent

實用指南:在處理敏感資料的 Agent 中,運用 LangGraph 人工審核、檢查點、執行上限,以及安全管理憑證的工具。

AI

摘要 · TL;DR

使用 LangGraph 的人機協作中介軟體暫停敏感工具呼叫,以便審核或拒絕,並從檢查點恢復執行。搭配嚴格的工具權限界線、憑證隔離與執行上限,打造更安全的流程。

重點

  • 將憑證留在工具實作內;只傳遞模型執行所需的最少參數。
  • 敏感寫入或查詢須經人工審核;安全的讀取操作則可直接執行。
  • 使用持久化 checkpointer 與穩定的 thread ID,恢復遭中斷的工作。
  • 限制圖的執行範圍,並讓工具具備冪等性,或確保重試本身安全。
  • 將檢查點狀態與中斷負載視為敏感資料。
文章目錄 (5)

重視隱私的 Agent 不應仰賴模型自行判斷工具呼叫是否安全。應將憑證排除在對話之外、限制各工具可執行的操作,並在執行敏感動作前暫停以供人工審核。LangGraph 的人機協作中介軟體提供暫停與恢復機制;至於資料處理、授權與執行限制,仍須由你的應用程式自行定義。

本指南將示範一種精簡模式:Agent 可讀取客戶紀錄,並提出資料庫變更請求。此處程式碼僅供說明,未經測試。部署前,請依你的環境確認套件版本與工具簽章。

1. 將模型上下文與憑證分開

請勿將密碼、API 金鑰、工作階段 Cookie,或不受限制的資料庫憑證放入提示或工具參數。相反地,應提供權限範圍明確的工具操作,並讓工具在執行時透過應用程式的祕密管理機制取得憑證。模型只應看到選擇動作所需的資料。

例如,與其提供可接受任意 SQL 和連線資訊的通用工具,不如使用 find_customer_record(customer_id) 這類工具。請在工具本身驗證授權:使用者提出請求,並不能證明他們有權存取指定紀錄。

人工審核是額外的控管措施,不是授權系統。審核者應取得足以做出決定的資訊,但審核畫面與日誌中不應顯示不必要的個人資料或機密。

2. 為敏感操作設定審核機制

提供的 LangChain 人機協作文件介紹了一種中介軟體,可依照政策檢查工具呼叫。符合條件的呼叫可中斷執行;checkpointer 會保存圖的狀態,讓執行之後得以恢復。文件列出的決策包括核准、編輯參數、附上意見拒絕,以及回覆向使用者提問的工具。

以下是設定範例。請將佔位工具替換為符合應用程式存取規則並會驗證輸入的實作。

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="YOUR_CONFIGURED_MODEL",
    tools=[read_customer_record, update_customer_record],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "read_customer_record": False,
                "update_customer_record": {
                    "allowed_decisions": ["approve", "edit", "reject"]
                },
            },
            description_prefix="Review requested customer-data change",
        ),
    ],
    # For production, use a persistent checkpointer appropriate to your stack.
    checkpointer=InMemorySaver(),
)

InMemorySaver 適合用於原型開發,但不適合在程序重新啟動後持久復原。文件指出,人工作業中斷需要 checkpointer,並列出 AsyncPostgresSaver 和 MongoDBSaver 等持久化選項。請依據檢查點資料的敏感程度,選擇具備適當存取控制、保留規則與加密機制的儲存方式。即使排除了憑證,檢查點仍可能包含訊息與工具參數,因此可能存有敏感的使用者資料。

如果只有特定呼叫需要審核,文件也支援使用 when predicate 設定條件式中斷(需要 langchain>=1.3.3)。例如,你可以暫停對核准工作區以外的寫入,或非唯讀查詢。請勿將字串前綴檢查視為完整的 SQL 安全政策;也應在資料庫與工具層級強制執行安全操作。

3. 暫停、審核,並恢復同一個執行工作

使用穩定的 thread ID,讓應用程式能將待審核項目關聯到正確的對話。請妥善保護此識別碼與審核介面:僅持有 thread ID,不應就取得核准動作的權限。

from langgraph.types import Command

config = {"configurable": {"thread_id": "conversation-123"}}

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Update this customer's address"}]},
    config=config,
    version="v2",
)

if result.interrupts:
    # Present the requested action to an authenticated reviewer.
    # Resume only after recording that reviewer's decision.
    result = agent.invoke(
        Command(resume={"decisions": [{"type": "reject", "message": "Verify the request first."}]}),
        config=config,
        version="v2",
    )

如果多個工具呼叫同時暫停,決策順序必須與中斷請求中的動作順序一致。使用 reject 拒絕會產生副作用的動作。文件提醒,respond 會提供合成的工具結果;此選項適用於回覆「詢問使用者」類型的工具,不可用來拒絕寫入操作。

4. 限制執行範圍並設計復原機制

審核暫停本身無法防止模型反覆要求呼叫工具。請設定圖的遞迴上限,並將因此產生的上限錯誤處理為受控停止。實際上限取決於工作負載;請依據模型與工具步驟組成的最長有效序列設定,並測試觸及上限時的行為。

config = {
    "configurable": {"thread_id": "conversation-123"},
    "recursion_limit": 12,
}

此範例設定會限制圖的步驟數,但無法保證工具不會執行過久、輸出不會過大,或外部副作用不會重複發生。請為網路與資料庫呼叫加入逾時設定、限制工具輸出,並驗證輸入。對於可重試的操作,請使用冪等性控管,或在套用變更前檢查目前狀態。如果工具已成功執行,但 Agent 尚未記錄結果時執行失敗,盲目重試可能會讓同一操作執行兩次。

復原時,只有在確認待執行動作及其授權仍然有效後,才可從同一個已建立檢查點的 thread 恢復。如果審核等待期間使用者權限或底層紀錄已有變動,應拒絕執行或重新驗證,而不是使用過時的參數執行。

5. 隱私與故障檢查清單

正式上線前,請確認:

  • 工具實作會私下取得憑證,絕不在工具結果或錯誤訊息中回傳憑證。
  • 每個工具都會驗證使用者授權,並且只接受完成任務所需的最精簡參數。
  • 檢查點、中斷負載、日誌與審核者畫面皆有明確的存取和資料保留控管。
  • 審核者能辨識操作對象與影響,而不必查看無關的個人資料。
  • 拒絕操作時不會執行工具,且重試不會造成副作用重複發生。
  • 執行工作設有步驟上限、工具逾時與輸出限制,並有明確管道回報遭中斷或失敗的工作。

關鍵的設計原則,是將人工核准視為安全工作流程中的一個檢查點,而非最小權限、資料最小化或工具層級驗證的替代品。

常見問題

LangGraph 的人機協作中介軟體會儲存暫停中的 Agent 狀態嗎?

它會使用 LangGraph 持久化功能,在中斷期間保存狀態。此功能需要 checkpointer;正式環境部署應選擇持久化儲存,並採取適當的存取與保留控管。

應該使用 respond 決策來拒絕敏感工具呼叫嗎?

不應如此。根據文件所述,respond 會提供合成的成功工具結果,適用於回覆 ask-user 類型工具等情境。若要拒絕會產生副作用的動作,請使用 reject。

如何在 LangGraph Agent 中保護憑證?

將憑證存放在工具的執行環境或祕密管理層中。請勿將憑證放入提示、模型可見的工具參數、工具結果、中斷訊息或日誌。

人工核准能防止 Agent 無限執行嗎?

不能。核准中介軟體負責審核已設定的工具呼叫。請另外加入執行上限、工具逾時、輸出限制與安全的重試機制。

相關文章