打造具備隱私保護、工具核准與復原機制的 LangGraph Agent
實用指南:在處理敏感資料的 Agent 中,運用 LangGraph 人工審核、檢查點、執行上限,以及安全管理憑證的工具。
摘要 · 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 無限執行嗎?
不能。核准中介軟體負責審核已設定的工具呼叫。請另外加入執行上限、工具逾時、輸出限制與安全的重試機制。
相關文章
指南
打造具有限制執行邊界與人工審查的 LangGraph 工具呼叫代理
一套實用模式:透過明確的步驟限制、對高風險操作進行人工核准,以及可重複的測試案例,評估 LangGraph 工具呼叫代理。
指南
使用工具呼叫、人工作業核准與執行限制,建立 LangGraph 客戶支援代理
以實務導向的 LangGraph 模式建構客戶支援分流:路由請求、呼叫查詢工具、暫停退款流程等待人工核准,並限制圖形執行範圍。
指南
打造有界限的 LangGraph Agent,診斷 API 事件
打造 LangGraph 事件診斷 Agent,呼叫唯讀診斷工具、限制執行範圍、揭露失敗,並在執行高風險操作前暫停。
指南
打造具有限制執行步數、可驗證結構化資料的 LangGraph Agent
建立 LangGraph 工作流程,讓 Agent 在需要時呼叫工具、在預設執行預算內停止,並回傳符合 Pydantic schema 驗證的結構化資料。