人によるレビューを組み込んだ、実行範囲を制限した 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 は、グラフの実行ステップに上限を設けます。これは安全境界であり、エージェントが完了することの保証でも、ツール呼び出し回数の正確な上限でもありません。ステップの数え方はグラフ構造の影響を受けます。実行が上限に達した場合は、グラフの recursion error が発生すると考え、その実行を未完了として扱います。成功した回答として扱わないでください。
評価中は小さな制限から始め、テストケースによってワークフローにさらにステップが必要だと示された場合に限って引き上げます。また、ツールの操作範囲を狭く保ってください。グラフレベルの制限では、ツールがすでに実行した副作用を取り消せません。
レビューで一時停止できるツール呼び出しを設定する
この例では、HITL middleware と create_agent を使用します。write_file ツールは承認または拒否のために中断され、read_data は中断されません。ツールの実装とモデル名はプレースホルダーです。選択したモデルとエンドポイントが、エージェントで使用するパラメーターとツール呼び出しの挙動をサポートしていることを確認してください。
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 は、1つのプロセスで実行するプロトタイプやテストには適していますが、プロセスの再起動後も保持される永続ストレージではありません。デプロイするワークフローでは、永続的な checkpointer を使用してください。LangChain の HITL ガイドでは、実行を一時停止して再開するには checkpointer と thread ID が必要だと説明されています。出典:Human-in-the-loop。
実行結果が interrupt を返したら、要求されたアクションとその引数をレビュアーに表示します。同じ thread を使い、判断を渡して再開してください。判断の順序は、interrupt 内のアクションの順序と一致していなければなりません。拒否するアクションには reject を使います。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 またはモックしたツールを使用し、評価ケースによって実際のファイルに書き込んだり、本番データを変更したりしないでください。
| ケース | セットアップ | 期待する結果 |
|---|---|---|
| 安全な読み取り | read_data を通じて情報を要求する | HITL interrupt は発生せず、ツール結果が返される |
| レビュー対象の書き込み | 許可された書き込みを要求する | 書き込みの実行前に interrupt が表示され、承認すると実行される |
| 拒否された書き込み | 書き込みを要求してから拒否する | 書き込みツールは実行されず、拒否のフィードバックがエージェントに返される |
| ステップ制限の境界 | ワークフローが完了しない fixture を使用する | 設定した境界で実行が停止し、未完了として記録される |
各実行について、ケース ID、設定した制限、ツール呼び出し、interrupt に対する判断、完了ステータス、エラーを記録します。それらの項目を期待値と比較してください。最終的な自然言語の回答だけで判断するのは避けます。エージェントは、誤ったアクションを取った後でももっともらしい回答を生成できるためです。
失敗への対応:一時停止、拒否、停止
HITL は制御された一時停止であり、汎用的なリトライ機構ではありません。レビュアーは、設定されたポリシーに応じて承認、編集、拒否、または応答できます。拒否すると要求されたツール呼び出しはスキップされ、拒否のフィードバックがエージェントに返されます。その後エージェントが完了するのか、別のアクションを求めるのか、失敗するのかは、その後の挙動に依存するため、その経路をテストしてください。
グラフが recursion limit に達した場合は、その実行を制限到達による失敗として記録し、状態とツール履歴を確認します。すでに副作用を実行している可能性のある実行を自動的に再生しないでください。可能な場合はツールを冪等にするか、操作を繰り返す前に別途チェックを必須にします。提供されているドキュメントは、チェックポイントを使った一時停止と再開について説明していますが、任意のツールまたはモデルの失敗からの自動復旧を示すものではありません。
トラブルシューティングチェックリスト
- interrupt が表示されない: ツール名が
interrupt_onのマッピングと一致していること、またそのポリシーでレビューが有効になっていることを確認します。 - 再開時に一時停止した実行が見つからない: 同じ checkpointer と thread ID が使われていることを確認します。
- 実行が早く停止する: 設定した recursion limit とグラフの経路を確認します。テストケースが必要性を示した場合に限って制限を引き上げてください。
- 拒否したアクションが実行されたように見える: レビュー前にツールが呼び出されていないこと、レビュアーが
respondではなくrejectを使ったことを確認します。 - テスト結果が実行ごとに変わる: ツールの fixture とテスト入力を固定し、環境で可能な場合はモデルの応答を制御またはスタブ化します。入力を固定するだけでは、モデル出力は決定的になりません。
実践上のルール
recursion limit でグラフの作業範囲を制限し、HITL で重要なツール呼び出しを制御し、明示的で小規模なテストセットで正常系と失敗系の両方を検証します。中断、拒否、制限到達による未完了を、互いに異なる結果として扱ってください。この区別によって、エージェントの評価と変更が容易になり、安全性も高まります。
よくある質問
LangGraph の recursion limit はツール呼び出し回数の上限ですか?
厳密には違います。制限するのはグラフの実行ステップであり、収められるツール呼び出しの数はグラフ構造によって異なります。制限到達は未完了の実行として扱い、その境界をテストしてください。
人によるレビューを受けたツール呼び出しを再開するには何が必要ですか?
checkpointer を設定し、thread ID を指定したうえで、同じ thread と永続化コンテキストを使って再開します。レビュアーは、中断された各アクションに対する判断を渡します。
HITL は失敗したツール呼び出しを自動的にリトライしますか?
いいえ。文書化されている HITL ワークフローは、人による判断のために一時停止し、その後にレビュー対象のアクションを実行またはスキップします。任意のツールまたはモデルの失敗に対する自動リトライを示すものではありません。
拒否されたツール呼び出しはどのようにテストすべきですか?
無害なツールまたはモックしたツールを使い、interrupt を発生させてアクションを拒否します。そのうえで、ツールが実行されていないことと、実行に拒否のフィードバックが記録されていることを検証します。
関連記事
Guides
ツール承認と復旧に対応した、プライバシー配慮型LangGraphエージェントの構築
LangGraphの人間によるレビュー、チェックポイント、実行制限、認証情報を安全に扱うツールを組み合わせ、機密データを扱うエージェントを構築する実践的なパターンを紹介します。
Guides
LangGraphのツール呼び出し:実行回数の制限と障害からの復旧
無制限の実行ではなく、再試行回数の上限、人による承認、明示的な復旧経路を備えたLangGraph本番運用エージェントの構築方法を解説します。
Guides
APIインシデント診断用のLangGraphエージェントを構築する
読み取り専用の診断ツールを呼び出し、実行を制限し、失敗を明示して、リスクのある操作の前に一時停止するLangGraphインシデント診断エージェントを構築します。
Guides
ツール呼び出し・人間による承認・実行制限を備えたLangGraphカスタマーサポートエージェントの構築
カスタマーサポートのトリアージに使えるLangGraphの実践パターンを紹介。問い合わせの振り分け、検索ツールの呼び出し、人による承認まで返金を保留する方法、グラフ実行を制限する方法を解説します。