打造具有限制執行邊界與人工審查的 LangGraph 工具呼叫代理
一套實用模式:透過明確的步驟限制、對高風險操作進行人工核准,以及可重複的測試案例,評估 LangGraph 工具呼叫代理。
摘要 · TL;DR
使用圖形步驟限制來界定執行範圍,使用 HumanInTheLoopMiddleware 暫停高風險工具呼叫,並透過小型固定測試集檢查核准、拒絕與限制行為。請將範例視為起點:模型與工具行為必須在你自己的環境中測試。
重點
- 圖形 recursion limit 能為代理設定明確的執行邊界,但不保證代理會完成任務。
- 當圖形具備 checkpointer 與 thread ID 時,人工審查可以暫停工具執行,並在之後恢復。
- 固定測試輸入、預期結果、工具 fixture 與執行限制,讓評估保持可重複。
- 明確測試遭拒的操作與限制耗盡;兩者都不等同於成功復原。
文章目錄 (6)
工具呼叫代理需要的不只是好的提示:它需要停止邊界、處理高風險操作的方案,以及能讓行為可重現的測試。在 LangGraph 中,你可以將圖形 recursion limit 與針對特定工具的人在迴路(human-in-the-loop,HITL)審查結合。接著,使用固定案例評估工作流程,而不是只依賴少數幾次成功執行。
以下範例僅供說明,並非經過測試的設定。它假設你使用具備相容 LangChain 與 LangGraph 套件的 Python 環境、支援工具呼叫的聊天模型,以及你已實作的工具。請在自己的環境中確認版本與模型供應商參數。
在加入工具前選定邊界
recursion limit 會限制圖形的執行步驟。它是安全邊界,不代表代理一定會完成任務,也不是工具呼叫次數的精確上限:步驟如何計算會受到圖形結構影響。如果執行達到限制,預期會出現圖形遞迴錯誤,並將其視為未完成的執行來處理。不要把它當成成功的答案。
評估期間先使用較小的限制,只有在測試案例顯示工作流程需要更多步驟時,才提高限制。同時,讓工具操作保持明確且範圍狹窄。圖形層級的限制無法撤銷工具已經執行的副作用。
設定可暫停審查的工具呼叫
此範例使用搭配 HITL middleware 的 create_agent。write_file 工具會在核准或拒絕前中斷;read_data 則不會。工具實作與模型名稱都是 placeholder。請確認你選用的模型與端點支援代理使用的參數及工具呼叫行為。
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
# Replace these placeholders with your own tool implementations.
tools = [write_file, read_data]
agent = create_agent(
model="your-tool-capable-chat-model",
tools=tools,
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"write_file": {"allowed_decisions": ["approve", "reject"]},
"read_data": False,
}
)
],
checkpointer=InMemorySaver(),
)
config = {
"configurable": {"thread_id": "evaluation-case-001"},
"recursion_limit": 8,
}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Save the approved summary."}]},
config=config,
version="v2",
)
InMemorySaver 適合原型或在單一程序中執行的測試;程序重新啟動後,它不具備持久性。對於部署中的工作流程,請使用持久化 checkpointer。LangChain 的 HITL 指南說明,若要暫停並恢復執行,就需要 checkpointer 與 thread ID。來源:Human-in-the-loop。
當執行結果回傳 interrupt 時,請將要求的操作及其參數顯示給審查者。使用決策恢復同一個 thread。決策順序必須與 interrupt 中的操作順序一致。拒絕要阻止的操作;respond 是用來將人工回答作為工具結果回傳,而不是用來拒絕副作用。
from langgraph.types import Command
# Use the same config, including the same thread ID, to resume.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Outside the approved scope."}]}),
config=config,
version="v2",
)
讓評估可重複
將精簡的測試集納入版本控制。每個案例都應指定使用者要求、預期的工具行為、是否需要審查,以及預期的最終狀態。測試時請使用無害的 fixture 或 mock 工具;不要讓評估案例寫入真實檔案或變更正式環境資料。
| 案例 | 設定 | 預期結果 |
|---|---|---|
| 安全讀取 | 透過 read_data 要求資訊 | 不會出現 HITL interrupt;回傳工具結果 |
| 經審查的寫入 | 要求執行允許的寫入 | 寫入執行前出現 interrupt;核准後允許執行 |
| 遭拒的寫入 | 要求寫入,接著拒絕 | 不會執行寫入工具;拒絕回饋會回傳給代理 |
| 步驟限制邊界 | 使用讓工作流程無法完成的 fixture | 執行在設定的邊界停止,並記錄為未完成 |
每次執行都記錄案例 ID、設定的限制、工具呼叫、interrupt 決策、完成狀態及任何錯誤。將這些欄位與預期結果比較。不要只根據最終的自然語言回應進行判斷:代理可能在採取錯誤操作後,仍然產生看似合理的答案。
失敗處理:暫停、拒絕或停止
HITL 是受控的暫停機制,不是通用的重試機制。審查者可以依照設定的政策進行核准、編輯、拒絕或回覆。拒絕會略過要求的工具呼叫,並將拒絕回饋回傳給代理。代理接著會完成、要求另一項操作,或是失敗,取決於其後續行為,因此請測試這條路徑。
如果圖形達到 recursion limit,請將執行記錄為限制失敗,並檢查其狀態與工具歷程。不要自動重播可能已經執行副作用的執行。實際可行時,讓工具具備冪等性,或在重複操作前要求額外檢查。提供的文件說明了具備 checkpoint 的暫停與恢復,但沒有建立針對任意工具或模型失敗的自動復原機制。
疑難排解清單
- 沒有出現 interrupt: 確認工具名稱符合
interrupt_on對應設定,且其政策已啟用審查。 - 恢復時找不到暫停的執行: 確認使用的是同一個 checkpointer 與 thread ID。
- 執行提早停止: 檢查設定的 recursion limit 與圖形路徑;只有在測試案例有充分理由時才提高限制。
- 遭拒的操作似乎已經發生: 確認審查前沒有呼叫工具,並確認審查者使用的是
reject而非respond。 - 測試結果每次執行都不同: 固定工具 fixture 與測試輸入,並在設定允許的情況下控制或 stub 模型回應。只有固定輸入,並不足以讓模型輸出具備決定性。
實務規則
使用 recursion limit 限制圖形工作量,使用 HITL 閘控具重大影響的工具呼叫,並以小型且明確的測試集驗證成功路徑與失敗路徑。將中斷、遭拒與限制耗盡的執行視為不同結果。這種區分能讓代理更容易評估,也更安全地進行變更。
常見問題
LangGraph 的 recursion limit 會限制工具呼叫次數嗎?
不完全是。它限制的是圖形執行步驟,而可容納的工具呼叫次數取決於圖形結構。請將限制耗盡視為未完成的執行,並測試這個邊界。
要恢復經人工審查的工具呼叫,需要什麼條件?
設定 checkpointer、提供 thread ID,並使用相同的 thread 與持久化內容恢復。審查者要為每個中斷的操作提供決策。
HITL 會自動重試失敗的工具呼叫嗎?
不會。文件描述的 HITL 工作流程會暫停以等待人工決策,接著執行或略過經審查的操作。它沒有建立針對任意工具或模型失敗的自動重試機制。
應如何測試遭拒的工具呼叫?
使用無害或 mock 工具,觸發 interrupt,拒絕該操作,並驗證工具未被執行,且執行結果記錄了拒絕回饋。
相關文章
指南
打造具備隱私保護、工具核准與復原機制的 LangGraph Agent
實用指南:在處理敏感資料的 Agent 中,運用 LangGraph 人工審核、檢查點、執行上限,以及安全管理憑證的工具。
指南
打造有界限的 LangGraph Agent,診斷 API 事件
打造 LangGraph 事件診斷 Agent,呼叫唯讀診斷工具、限制執行範圍、揭露失敗,並在執行高風險操作前暫停。
指南
使用工具呼叫、人工作業核准與執行限制,建立 LangGraph 客戶支援代理
以實務導向的 LangGraph 模式建構客戶支援分流:路由請求、呼叫查詢工具、暫停退款流程等待人工核准,並限制圖形執行範圍。
指南
LangGraph Agentic RAG:工具呼叫、來源歸屬與有界執行
建立 LangGraph 文件問答代理,讓它決定何時擷取資料、評估上下文、重試效果不佳的搜尋,並在不進行無限執行的情況下,返回附有來源歸屬的答案。