AIエージェントの処理で一番困るのは、答えを作る部分よりも「途中で人に確認したい」「確認の翌日に続きから動かしたい」という場面かもしれません。外部送信や発注の前に一度止めたいのに、プロセスを止めると状態が失われる。再実行すると、既に終えた処理をもう一度走らせてしまう。その境界を明確に扱うために、LangGraphにはcheckpointerとinterrupt()があります。
この記事では、LLMや有料APIを使わない小さなPythonの例で「下書きを作る→人間が確認する→承認なら完了」という流れを組み立てます。狙いはLangGraphの全機能を網羅することではありません。同じthread_idでどの状態を再開するのか、再開時にどのコードがもう一度動くのか、メモリ上の保存と永続保存はどう違うのかを理解することです。
要点:中断・再開にはcheckpointerと安定した
thread_idが必要です。interrupt()の手前に外部書き込みを置くと、再開時の再実行で二重処理になるおそれがあります。「保存したから安全」ではなく、副作用をどこで実行し、実行済みをどう確かめるかまで設計します。

まず用語を分ける
LangGraphのノードは、現在のstateを受け取って更新を返す処理です。グラフはノード同士の流れを表し、invoke()などで動かします。checkpointerは、特定のスレッドについてグラフの状態を保存する仕組みです。thread_idはそのスレッドを指定する識別子で、同じ値を渡すと同じ状態の続きを参照します。別の値を使うと、別の作業として扱われます。
interrupt()はノードの途中で実行を一時停止し、呼び出し側へ「人間へ見せたい情報」を返す関数です。人が判断したらCommand(resume=...)で再開できます。公式ドキュメントは、interruptの値をJSONで表せるものにし、再開時には同じthread_idを使うよう説明しています。承認待ちに限らず、足りない入力を本人に尋ねる、処理結果を編集してもらう用途にも使えます。
似ている言葉としてstoreがあります。公式資料は、checkpointerを「一つのスレッドのグラフ状態」、storeを「スレッドをまたぐアプリケーション定義のデータ」に分けています。作業の途中経過を再開したいならcheckpointer、ユーザーの継続的な好みや共通知識を別の作業にも使いたいならstore、という理解から始めると混乱しにくいでしょう。checkpointerに何でも長期記憶として詰める必要はありません。
中断と承認は同じではない
interrupt()は「止まる」機能です。「承認された」と判断するのは、再開値を受け取るアプリケーション側のコードです。たとえば{"approved": false}が返ってきた場合には送信ノードへ進めない条件を自分で実装します。逆にinterrupt()を置いただけで、外部APIへの送信が自動で保護されるわけでもありません。判断をUIで入力する人の識別、承認対象の内容、権限、期限などは別途設計が必要です。
最小の承認フローを作る
以下の例は、入力された文章を整えるノードと、人に最終確認を求めるノードを持ちます。外部メール送信や投稿はしません。まずライブラリを仮想環境へ導入してください。実際のプロジェクトでは、使用している依存管理方法へ合わせ、バージョンを固定してテストすることを勧めます。LangGraphのAPIは更新されるため、公式ドキュメントと使用バージョンをセットで確認してください。
python -m venv .venv
source .venv/bin/activate
python -m pip install langgraph
サンプルのstateは、原稿、提案文、承認結果、最終文の四つです。InMemorySaverを使うため、同じPythonプロセスでの挙動確認に限ります。プロセスを終了して再起動すれば、この保存内容は失われます。後半で、実運用の保存先を考えます。
from typing import TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import END, START, StateGraph
from langgraph.types import Command, interrupt
class ReviewState(TypedDict, total=False):
source: str
proposal: str
approved: bool
final_text: str
def prepare(state: ReviewState) -> ReviewState:
return {"proposal": state["source"].strip()}
def review(state: ReviewState) -> ReviewState:
decision = interrupt({
"action": "review_proposal",
"proposal": state["proposal"],
})
approved = decision.get("approved") is True
if not approved:
return {"approved": False, "final_text": ""}
final_text = decision.get("edited_text") or state["proposal"]
return {"approved": True, "final_text": final_text}
builder = StateGraph(ReviewState)
builder.add_node("prepare", prepare)
builder.add_node("review", review)
builder.add_edge(START, "prepare")
builder.add_edge("prepare", "review")
builder.add_edge("review", END)
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "review-example-001"}}
paused = graph.invoke({"source": " 確認用の原稿 "}, config=config)
print(paused["__interrupt__"])
resumed = graph.invoke(
Command(resume={"approved": True, "edited_text": "確認済みの原稿"}),
config=config,
)
print(resumed["approved"], resumed["final_text"])
初回のinvoke()ではreview()内のinterrupt()で停止します。呼び出し側は__interrupt__を読んで提案文を表示し、人が承認または修正した値を用意します。二回目のinvoke()では同じconfigを使い、Command(resume=...)を渡します。この値が、停止していたinterrupt()の戻り値になります。
この例では、単にapprovedが真かどうかだけを見ています。本番では「誰が、どの提案の、どの版を承認したか」を記録する方が安全です。画面を開いている間に提案文が変わったら、古い承認を新しい内容へ流用してはいけません。承認対象のハッシュやバージョンを持ち、再開時に一致を検証する設計が考えられます。
thread_idを変えるとどうなるか
中断後の状態はthread_idに紐づきます。再開時に別のIDを渡せば、それは別のスレッドです。「一時停止から復帰できない」というとき、まずIDが保存時と一致しているかを確認します。固定文字列review-example-001は説明用です。実際には衝突しない値を割り当て、機密情報そのものをIDに埋め込まない方が扱いやすくなります。
同じIDを利用する作業同士が並走する場合にも注意が必要です。二つの画面が同じスレッドを勝手に進めると、どちらの承認をどの状態へ適用するか曖昧になります。並走を許すなら、書き込みの整合性、版、操作順序を管理する必要があります。まずは「一つのレビュー案件に一つの安定ID」という単純なルールで始めましょう。
再開時にはノードの先頭から動く
公式ドキュメントが強調する重要な点は、interrupt()を含むノードが再開すると、そのノードの先頭から再実行されることです。以下は避けたい形です。
def unsafe_review(state: ReviewState) -> ReviewState:
# ここで外部送信すると、再開時にもう一度送る可能性がある
send_to_external_service(state["proposal"])
decision = interrupt({"proposal": state["proposal"]})
return {"approved": decision.get("approved") is True}
この例は構文の説明用で、send_to_external_serviceの実体はありません。実行可能なサンプルではなく、危険な配置を示しています。再開時にノードの先頭から始まるなら、interrupt()より前の送信が繰り返されるおそれがあります。承認前の外部送信は意味的にもおかしいので、外部操作は承認済みの別ノードへ分けるのが基本です。
ただし、別ノードにしただけで重複が完全に消えるわけではありません。送信中にネットワークが切れ、相手には届いたがこちらが成功を確認できない場合、再試行が二重送信になることがあります。可能なら外部APIのidempotency keyを使い、送信済みを識別できるようにします。APIがその仕組みを持たないなら、書き込み前後の照合と、結果が曖昧なときに自動再送しない停止条件を用意します。




InMemorySaverを本番保存と思わない
このサンプルのInMemorySaverは、名前の通りプロセスのメモリ上にチェックポイントを持ちます。公式のPersistenceページは、MemorySaverとInMemorySaverが再起動後に状態を残さないと明記しています。ローカルの動作確認には便利ですが、翌日人が承認するフローや、アプリが再起動する運用には向きません。
本番の保存先には、必要な耐久性に応じた永続checkpointerを選びます。公式資料はローカル開発のSQLiteと、本番用途のPostgresの選択肢を案内しています。ただし「Postgresに置いたから必ず復旧できる」わけではありません。接続設定、バックアップ、アクセス制御、保持期間、スキーマの移行、再起動後の再開テストまでが運用です。
チェックポイントには、原稿や判断情報のような機密内容が含まれることがあります。どの値をstateへ入れるかは、保存期間と閲覧権限を考えて決めてください。巨大な添付ファイルや秘密鍵をstateへ直接入れるより、権限管理された別の保管先に置き、その参照IDだけを持つ方が適切な場合があります。ログへstate全体を無条件に出すのも避けます。
storeが必要になる場合
たとえば「このユーザーは専門用語の説明を短くしてほしい」という継続的な好みを、別の記事レビューでも使いたいとします。これは一つのレビュー案件の途中経過とは違います。LangGraphのstoreは、こうしたスレッドをまたぐアプリケーション定義データを扱うための仕組みです。ただし、保存してよい情報の範囲や本人による訂正・削除の方法はアプリケーション側で決める必要があります。
まずはcheckpointerだけで停止・再開を完成させ、跨ぎの記憶が本当に必要になってからstoreを追加する方が、どのデータがどこに保存されるか見失いにくくなります。二つを同時に入れると、現在の状態と長期記憶のどちらが正本なのか曖昧になることがあります。使い分けを明文化しましょう。
人間の画面とグラフをつなぐとき
実際のレビュー画面では、まず停止した案件の一覧を出し、提案文と操作対象を本人に見せます。承認・修正・却下のいずれかを選べるようにし、送信前に最終内容を確認します。UIが返す値をそのまま信用せず、サーバー側で案件ID、権限、期限、版を検証してください。承認者が違う案件のthread_idを推測して再開できる状態は避けます。
結果が曖昧なときは「未承認」に戻すのではなく、状態を読み直します。たとえば承認ボタンを押した直後に画面がタイムアウトしても、再度押す前に、グラフが既に再開したか、外部操作が行われたかを照合します。二重クリック防止のUIだけでなく、サーバー側の一意な操作IDも有効です。
一方で、何でも承認待ちにすると、自動化の価値が下がります。下書きの生成や読み取り専用の調査は自動で進め、外部送信、購入、削除、公開のように影響が大きい境界だけを人間に示すと分かりやすくなります。承認画面では「何を」「どこへ」「いつ」「変更後にどう戻せるか」を短く提示します。
中断中に内容が古くなった場合
人間の確認には時間差があります。昨日作った提案が今日も正しいとは限りません。たとえば外部サービスの料金、記事の公開日時、処理対象のファイル数が変わった場合、昨日の承認画面に出した値と、実行直前の値が違うかもしれません。再開時には、元の提案に含まれる重要な値を読み直し、差が大きければ新しい提案として本人に確認し直す方が安全です。thread_idが同じであることは、外部世界が変わっていない証明にはなりません。
画面に渡すpayloadは、単なる「承認してください」より、対象の識別子、提案の要約、影響、確認時刻を含めた方が誤操作を減らせます。一方で、個人情報を含む全文を通知やログにばらまく必要はありません。表示すべき情報と保存すべき情報を分け、詳しい内容は認証されたレビュー画面でだけ見せる設計が考えられます。承認結果には、承認・差し戻し・却下の区別を残すと、後で「なぜ進まなかったか」を追いやすくなります。
いつLangGraphを使うべきか
一つの関数で完結し、途中停止も再開も不要なら、普通のPython関数と明示的な条件分岐で十分です。グラフの概念や保存先を増やすと、かえって保守が難しくなる場合があります。一方、複数の処理段階があり、人間の入力や外部障害をはさんで安全に続きを進めたいなら、状態を明示したグラフには価値があります。採用の判断では、ノード数よりも「途中状態を本人や運用者が説明できるか」「失敗したときにどこから再開すべきか」が重要です。
よくある失敗と対処
停止できない場合、まずグラフをcheckpointer付きでcompileしたか、同じthread_idを渡しているか、interrupt()が実際に通る分岐かを確認します。サンプルが動くのにアプリで動かないなら、アプリの呼び出し側が中断結果を適切に保持し、画面へ渡しているかを調べます。見た目だけの「確認ボタン」があっても、グラフが停止していなければ安全なゲートにはなりません。
再開したら最初から全部やり直したように見える場合、同じthread_idかを調べた後、どのノードが再実行されたかを確認します。特にinterrupt()より前の処理を見ます。外部書き込みがそこにあるなら設計を変更し、既に行われた書き込みを特定します。何度も再実行して原因を探るより、まず対象システムの実状態を読み取る方が安全です。
再起動後に復旧できない場合、InMemorySaverを使っていないかを確認します。メモリ保存はプロセスをまたぎません。永続checkpointerへ変えても、保存先へ接続できなければ再開はできないため、障害時に何を本人へ知らせるかを決めておきます。正常系だけでなく、保存先停止、承認画面の再読込、同じ承認の再送をテストします。
実運用前のチェックリスト
- □ 同じ案件に安定した
thread_idを使っている - □ グラフをcheckpointer付きでcompileした
- □
interrupt()の手前に外部書き込みを置いていない - □ 承認対象の内容・版・操作先を画面に示している
- □ 承認値と承認者をサーバー側で検証している
- □ 曖昧な書き込み結果では再実行前に実状態を読む
- □ 本番の保存先は再起動後にも残る方式を選んだ
- □ stateとログに機密情報を過剰に入れていない
- □ 保存先停止、再開、二重操作のテストを行った
まとめ
LangGraphのinterrupt()は人間の判断が必要なところでグラフを止め、Command(resume=...)は同じthread_idの状態から続きを進めます。checkpointerはその途中経過を支えます。ただし、InMemorySaverは再起動を越えませんし、ノードの再実行で外部書き込みが重複する問題も自動で消えません。小さなサンプルで停止・再開を確認したら、次に承認対象の版、権限、永続保存、外部操作の一意性を設計する順番が安全です。

コメント