指南OneMux

打造具有限制執行邊界與人工審查的 LangGraph 工具呼叫代理

一套實用模式:透過明確的步驟限制、對高風險操作進行人工核准,以及可重複的測試案例,評估 LangGraph 工具呼叫代理。

AI

摘要 · 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,拒絕該操作,並驗證工具未被執行,且執行結果記錄了拒絕回饋。

相關文章