シンプルなwhileループでAIエージェントを作ったことがあれば、苦しみはご存知のはずです。モデルを呼び、ツールを実行し、結果を追加して繰り返す——そのループは数ステップで脱線し、一度クラッシュすると進行状況がすべて消え、エージェントが取り返しのつかない操作をする前に人間が介入するきれいな方法もありません。
LangGraphはLangChainチームのオープンソースプロジェクトで、まさにこの問題を解決するために作られました。ステートフルで長時間実行されるエージェントのための低レベルオーケストレーション框架であり、現在エージェント生態系で最も人気のある基盤の一つです(GitHubスター4万超、Klarna・Replit・Elasticなどが本番利用)。
問題:素朴なエージェントループが壊れる理由#
エージェントを、街中で20件の用事をこなす配達員に例えてみましょう。
- 素朴なループは、メモ帳を持たない配達員です。各用事の後にすべてを暗記する必要があり、気を取ると残りの荷物を忘れます。バイクが故障する(例外・タイムアウト・デプロイ)と、その日の仕事は全消しです。
- 本当に欲しいのはクリップボードを持つ配達員です。各用事の後に状態を書き留めれば、誰でも引き継げるし、上司は危険な配達の前にクリップボードを確認できます。
これがLangGraphの核心的な発想です:エージェントの状態(ステート)は第一級の市民。框架が状態を保存・復元し、実行中でも検査・修正できます。
解決策:エージェントをグラフとしてモデル化する#
LangGraphはエージェントを共有ステート上のグラフとしてモデル化します。概念を一つずつ見ていきましょう。
1. State — 共有ホワイトボード#
Stateはグラフ全体を流れるデータ構造(TypedDictまたはPydanticモデル)です。すべてのノードが読み取り、更新を書き込めます:
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages
class State(TypedDict):
# add_messagesは「reducer」:新しいメッセージは上書きでなく追記される
messages: Annotated[list, add_messages]
query: strpythonAnnotated[list, add_messages]の部分がリデューサーです。複数のノードが同じフィールドに書き込むときのマージ方法をLangGraphに伝えます——置き換えではなく追記です。
2. ノード — 処理ステップ#
ノードは現在のステートを受け取り、部分的な更新を返すただの関数です。重要なのは、ノードが決定論的なPythonコード(API呼び出し、バリデーション)にもLLM呼び出しにもなれること。両方を同じグラフに混在できます:
from langgraph.graph import StateGraph, START, END
from langchain.chat_models import init_chat_model
llm = init_chat_model("anthropic:claude-sonnet-4-5")
def chatbot(state: State):
return {"messages": [llm.invoke(state["messages"])]}
graph = StateGraph(State)
graph.add_node("chatbot", chatbot)
graph.add_edge(START, "chatbot")
graph.add_edge("chatbot", END)
app = graph.compile()
app.invoke({"messages": [{"role": "user", "content": "hi!"}]})python3. エッジ — 制御フロー#
- 通常のエッジ(
add_edge)は常にAからBへ進みます。 - 条件付きエッジ(
add_conditional_edges)はステートに応じて動的に経路を選びます——ここが「エージェント」の部分です:LLMがツールを呼ぶか終了するかを決めます。
典型的なエージェントの形は次のとおりです:
from langgraph.prebuilt import ToolNode, tools_condition
graph.add_conditional_edges("chatbot", tools_condition) # LLMが判断
graph.add_node("tools", ToolNode(my_tools))
graph.add_edge("tools", "chatbot") # ループバックpython4. Checkpointer — 耐久実行#
これがLangGraphのスーパーパワーです。チェッックポインターを追加すると、グラフは各ステップの後にステートを保存します:
from langgraph.checkpoint.memory import InMemorySaver
checkpointer = InMemorySaver() # 本番ではDB保存版を使う
app = graph.compile(checkpointer=checkpointer)
app.invoke(
{"messages": [{"role": "user", "content": "hi!"}]},
config={"configurable": {"thread_id": "user-123"}},
)pythonthread_idが一つの会話を識別します。プロセスが途中でクラッシュしても、同じスレッドIDで再実行すれば最後のチェックポイントから再開します——メモ帳はバイクの故障を生き延びるのです。
5. Interrupt — 人間をループに組み込む#
永続化があれば、承認待ちの一時停止は trivial になります:
app.invoke(input, config, interrupt_before=["tools"])pythonグラフはtoolsノードの直前で停止し、人間がステートを検査(修正も可能)してから再開します。メール送信・コード実行・支払いができるエージェントには必須の仕組みです。
なぜこの設計が強いのか#
| 能力 | LangGraphが提供するもの |
|---|---|
| 耐久実行 | 障害を乗り越え、長時間タスクを再開 |
| Human-in-the-loop | 危険なステップの前にエージェントの状態を検査・修正 |
| メモリ | 短期のワーキングメモリ + セッションを超える長期記憶 |
| 混在ロジック | 決定論的コードとLLMステップを監査可能な一つのグラフに |
| 可観測性 | LangSmithによる全ノード・状態遷移のトレース |
エージェント全体がグラフなので、可視化・再生・ステップごとのデバッグができます——絡み合ったwhileループには決してできないことです。
[!TIP] グラフを手で組みたくない場合は、LangGraphの上に構築されたプレビルトエージェント(
create_react_agent)や、計画・サブエージェント・ファイルシステムを使うエージェントのための高レベルパッケージDeep Agentsがあります。まずそこから始め、カスタム制御フローが必要になったら素のLangGraphに降りてきましょう。
いつ使うべきか?#
向いているケース: ツールを呼び、承認フローが必要で、数分〜数時間実行され、再起動を乗り越える必要がある多段階エージェント——カスタマーサポートbot、コーディングエージェント、リサーチパイプライン。
過剰なケース: 一発きりのQ&Aや、ツール呼び出しのない簡単なRAGチェーン。普通のLLM呼び出しや小さなチェーンの方がシンプルです。LangGraphが輝くのは、ステート・ループ・信頼性が重要になり始めた瞬間です。
実践例#
現実的なカスタマーサポートエージェントのグラフ:
各箱は小さくテストしやすい関数であり、チェックポインターにより日中のデプロイでも進行中の会話が破壊されません。小さな部品と耐久性のあるステートの組み合わせこそが、エージェントを本番対応にするのです。