LangGraphのツール呼び出し:実行回数の制限と障害からの復旧
無制限の実行ではなく、再試行回数の上限、人による承認、明示的な復旧経路を備えたLangGraph本番運用エージェントの構築方法を解説します。
要約 · TL;DR
本番運用エージェントに、無期限の再試行や副作用を伴う処理の無条件な繰り返しを許すべきではありません。LangGraphは実行を一時停止するためのグラフと永続化の仕組みを提供します。一方、ワークフロー側では再試行回数の上限、冪等性のルール、エスカレーション経路、復旧状態を定義する必要があります。HumanInTheLoopMiddlewareを使えば、リスクの高いツール呼び出しを承認待ちにし、承認・編集・却下・直接応答の後にチェックポイントから実行を再開できます。
要点
- 再試行するかどうかを決める前に、一時的な障害と恒久的な障害を区別する。
- ツールごとの再試行回数とグラフ全体のステップ上限の両方で実行を制限する。
- 本番リソースを作成・削除・変更するツールには冪等性キーを使う。
- 破壊的な操作や外部から見える操作には、人による承認を必須にする。
- グラフの状態を永続化し、中断したワークフローを最初からではなく途中から再開できるようにする。
目次 (9)
設計上の判断:自動で再試行するか、意図的に復旧するか?
本番ワークフローの運用では、「失敗したら何でも再試行する」を安全な既定動作にすべきではありません。基本方針は次のとおりです。
- 一時的な障害である可能性が高いエラーに限って再試行する。
- 明示した少ない試行回数の上限で停止する。
- 上限に達した処理や結果が不明な処理は、復旧状態に移す。
- 高額な損失や取り消せない結果につながる副作用の前には、承認を必須にする。
LangGraphが適しているのは、こうした結果を大きなエージェントループの中に隠すのではなく、グラフの状態として表現できるためです。モデルはツール呼び出しを提案できますが、その呼び出しを実行・再試行・エスカレーション・スキップしてよいかは、決定論的なコードで判断します。
以下の例は参考パターンです。テスト済みのアプリケーションではなく、正確なAPIはインストール済みのLangGraphおよびLangChainのバージョンによって異なる場合があります。
前提条件
必要なものは次のとおりです。
- Pythonと、互換性のあるLangGraphおよびLangChainパッケージ。
- 選択したインテグレーションを通じたツール呼び出しに対応するチャットモデル。
- 明示的な入力スキーマと予測可能なエラー型を持つツール。
- チェックポインター。実験には
InMemorySaverが適しています。LangGraphのドキュメントでは、本番環境にはAsyncPostgresSaverやMongoDBSaverなどの永続チェックポインターが推奨されています。 - ワークフローの実行ごとに一意で安定した
thread_id。
モデルに本番環境の認証情報への無制限なアクセスを与えないでください。認可、検証、冪等性、再試行ポリシーは、ツールまたはミドルウェア内に実装します。
再試行回数を制限できるツールを定義する
最初に設けるべき境界は、操作自体を囲む部分です。この例では、分類済みの一時的なエラーだけを再試行し、上限に達した場合は構造化された結果を返します。
from dataclasses import dataclass
from typing import Literal
class TransientOperationError(Exception):
pass
class PermanentOperationError(Exception):
pass
@dataclass
class OperationResult:
status: Literal["succeeded", "needs_recovery", "failed"]
attempts: int
message: str
def run_with_budget(operation, *, max_attempts: int) -> OperationResult:
for attempt in range(1, max_attempts + 1):
try:
operation()
return OperationResult("succeeded", attempt, "Operation completed")
except PermanentOperationError as exc:
return OperationResult("failed", attempt, str(exc))
except TransientOperationError as exc:
if attempt == max_attempts:
return OperationResult(
"needs_recovery", attempt,
f"Retry budget exhausted: {exc}",
)
return OperationResult("needs_recovery", max_attempts, "No attempt was made")
実運用では、再試行する前に冪等性キーを追加してください。デプロイ要求後にタイムアウトしたからといって、デプロイが実行されなかったとは限りません。キーなしで再試行すると、ジョブ、チケット、支払い、変更要求が重複して作成されるおそれがあります。
ポリシーの例を次に示します。
| 障害の分類 | 自動処理 | 復旧処理 |
|---|---|---|
| 一時的なネットワークタイムアウト | 上限内で再試行 | 操作IDを添えてエスカレーション |
| レート制限 | プロバイダーの指針に沿って再試行 | ワークフローをキューに入れるか延期 |
| 無効な引数 | 再試行しない | 検証エラーをエージェントに返す |
| 権限エラー | 再試行しない | 認可を求めるか停止 |
| タイムアウト後に結果が不明 | むやみに繰り返さない | 冪等性キーを使って状態を確認 |
ツール呼び出しと人による承認を追加する
LangChainのcreate_agentは、内部でLangGraphを使って実行されます。提供されているLangGraphのドキュメントでは、選択したツール呼び出しを中断し、永続化した状態から再開できるHumanInTheLoopMiddlewareが説明されています。
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model="provider:model-name",
tools=[inspect_job, restart_job, delete_artifact],
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"inspect_job": False,
"restart_job": {
"allowed_decisions": ["approve", "reject"]
},
"delete_artifact": {
"allowed_decisions": ["approve", "edit", "reject"]
},
},
interrupt_mode="per_call",
),
],
checkpointer=InMemorySaver(),
)
この例では、調査はレビューなしで実行され、再起動と削除は判断を待つために一時停止します。approveは元の引数で実行し、editは実行前に引数を変更し、rejectは呼び出しをスキップして却下のフィードバックをエージェントに返します。また、ソースでは「ユーザーに質問する」ツールとしてのrespondも説明されています。これは副作用のあるツールを拒否する目的で使うべきではありません。成功したツール結果として扱われるためです。
本番環境では、インメモリのチェックポインターを永続実装に置き換え、安定したスレッドIDを指定してエージェントを実行します。
config = {
"configurable": {"thread_id": "ops-workflow-1842"}
}
result = agent.invoke(
{
"messages": [
{
"role": "user",
"content": "Inspect the failed job and restart it if safe.",
}
]
},
config=config,
version="v2",
)
バージョンv2では、中断された結果にinterruptsコレクションが含まれます。要求された操作を権限のあるレビュアーに提示し、ドキュメントに記載されたCommandの判断形式を使って、同じスレッドを再開します。
再試行と承認を適切な順序で処理する
ソースドキュメントでは、ミドルウェアに関する重要なルールが説明されています。呼び出しごとのレビューを行う場合は、ヒューマン・イン・ザ・ループの処理を、ツールの再試行またはエラー処理のミドルウェアより前に配置してください。そうしないと、再試行によってレビュアーに再度確認が求められたり、無効な回答がツール障害として再試行されたりする可能性があります。
意図する処理順序は次のとおりです。
- モデルがツール呼び出しを提案する。
- ポリシーによってレビューが必要かどうかを確認する。
- レビュアーが呼び出しを承認、編集、または却下する。
- ツールが独自の上限付き再試行ポリシーで実行される。
- 成功した場合はエージェントに戻り、上限に達した場合は復旧処理に移る。
中断からの再開時に再実行されるミドルウェア内で、副作用を発生させないでください。ドキュメントでは、ヒューマンレビュー層より前のミドルウェアは、一時停止に至るまで複数回再入されても安全でなければならないと明確に警告しています。
再試行を重ねるのではなく、復旧状態を追加する
再試行回数の上限に達したら、ワークフローID、ツール名、試行回数、冪等性キー、最後に確認されたエラーを含む運用イベントを記録します。その後、次のいずれかを選択します。
- 確認: 外部システムを照会し、元の操作が成功したかを判断する。
- エスカレーション: 次の対応を判断するために必要な情報を添えて、オペレーターの確認を待つ。
- 補償: 別個の、明示的に承認された是正操作を実行する。
不完全なエラーメッセージをもとに、モデルに補償操作を考案させないでください。構造化された状態データを渡し、利用可能なツールを制限します。
グラフ全体の実行上限は、二つ目の安全境界です。インストール済みのLangGraphバージョンがサポートする上限を設定し、上限に達したら黙って続行するのではなく、復旧イベントとして扱います。これにより、モデルとツールのループが本番環境で無制限に実行されるのを防げます。
トラブルシューティングのチェックリスト
- ワークフローが最初から再開する: 永続チェックポインターを使っているか、
thread_idが変更されていないかを確認します。 - 却下した操作が実行される: 再開時の判断が
respondではなく、却下になっているかを確認します。 - レビュアーへの依頼が多すぎる: 引数に基づく
when述語を追加し、リスクの高い呼び出しだけを中断させます。 - 再試行で処理が重複する: 結果が不明な場合は、再試行の前に冪等性と状態確認用ツールを追加します。
- 同じレビューが繰り返し表示される: ミドルウェアの順序を確認し、再試行処理が承認の境界を不適切に囲んでいないことを確かめます。
- 編集した呼び出しが予想外の動作をする: 編集後の引数を自分で検証します。ドキュメントにあるレスポンススキーマは形式を示すものであり、業務上の安全性を必ずしも保証するものではありません。
まとめ
信頼性の高いLangGraph運用エージェントは、制約のないチャットボットではなく、実行に上限を設けたワークフローです。各ツールに再試行回数の上限を設定し、障害を分類し、状態を永続化し、危険な呼び出しに承認を求め、復旧を明示的な分岐として設計します。こうすることで、人による承認は緊急時の場当たり的な対応ではなく、ワークフロー内の管理されたチェックポイントになります。
参考資料
よくある質問
LangGraphは失敗したツール呼び出しをすべて自動で再試行しますか?
自動で再試行すると決めつけないでください。再試行の動作を明示的に定義し、エラーを分類して、最大試行回数を適用します。使用しているスタックでツール再試行ミドルウェアを利用できる場合もありますが、設定と動作はバージョンに対応したドキュメントで確認してください。
人による承認にチェックポイントが必要なのはなぜですか?
判断を待つ間、割り込みによって実行が一時停止するためです。チェックポインターはグラフの状態を保持し、承認・編集・却下・直接応答の後に、同じワークフロースレッドを再開できるようにします。
どのような場合にツール呼び出しの人によるレビューが必要ですか?
本番環境の状態を変更する、データを削除する、外部向けの連絡を送る、またはコストや影響範囲が不確かな呼び出しはレビューの対象にします。認可と出力の制限が明確であれば、読み取り専用の調査は自動実行できる場合があります。
再試行回数の上限に達したら、どうすべきですか?
復旧経路に移します。外部操作の結果を確認する、オペレーターにエスカレーションする、または別途承認された補償操作を実行します。結果が不明な操作をむやみに繰り返さないでください。
関連記事
Guides
LangGraphによるAgentic RAG:ツール呼び出し、出典明示、実行回数の制限
検索の要否を判断し、コンテキストの関連性を評価し、検索が不十分な場合は再試行するLangGraphの文書質問応答エージェントを構築します。実行回数を制限しながら、出典を明示した回答を返します。
Guides
人によるレビューを組み込んだ、実行範囲を制限した LangGraph ツール呼び出しエージェントの構築
明示的なステップ制限、リスクの高いアクションに対する人の承認、再現可能なテストケースを使って LangGraph ツール呼び出しエージェントを評価する実践的なパターンです。
Guides
Gemini 4 HydrogenとCarbonの比較:本番ワークフローの運用
Gemini 4 HydrogenとCarbonについて、コーディング、ツール呼び出し、構造化出力、および復旧可能な本番ワークフローに関して得られている根拠を整理します。
Guides
n8nで復旧可能なデータ抽出ワークフローを構築する
レコードの検証、一時的な障害の再試行、例外の担当者への振り分けを行い、重複書き込みを防ぐn8n抽出ワークフローを設計します。