LangGraphはGitHubで40k以上のstarsを集め、Agent编排の領域で最も使われているフレームワークの一つとなっている。 핵심思路は一言でいえば、Agentの実行フローを有向グラフとしてモデル化するということ。ループ、分岐、状態の永続化、人による承認まで、すべてグラフ構造の上で実現する。
以下では、課題、使い方、アーキテクチャ、長所と短所、実際の動作、向いているケースという六つの観点から整理する。
何の課題を解決するのか
従来のチェーン呼び出し(Chain)は一方向にしか進めない。prompt → llm → parser → nextという流れだ。Agentが必要とするループ(ReActのようにツールを何度も呼ぶ)、分岐(あるステップではtoolを呼び、次は直接回答する)、人による承認(途中で止めてユーザーに確認してから続行する)といった処理が出てくると、チェーン構造では行き詰まる。
LangChainのRunnableシーケンスにも同じ問題がある。本質的には同期で、有向で、一回きりの実行モデルだ。ロールバック、ポーズ、セッションをまたいだ記憶といった要件が出ると、Runnableでは力不足になる。
LangGraphはこの隙間を埋める。StateGraphを使って実行フローを明示的に有向グラフとしてモデル化する。
- ノード(Node) = 計算ユニット(LLM呼び出し1回、tool、関数)
- エッジ(Edge) = 遷移条件(無条件エッジ / 条件付きエッジ)
- 状態(State) = グローバルなデータ構造で、ノード間を自動で受け渡される
グラフは元々ループをサポートしているため、ReActのように反復が必要なAgentはグラフで表現するのが自然だ。
使い方
最初の3ステップは次のとおり。
- Stateを定義する(TypedDictまたはPydanticモデル)
- ノード関数を書く(stateを受け取り、stateの更新を返す)
StateGraphでグラフを組み立て、checkpointを設定してコンパイルする
中心的なAPIはadd_node、add_edge、add_conditional_edges、compileの4つだけ。
以下はそのまま動かせる最小例で、グラフと条件エッジの基本を3ステップのループで示す。
from typing import TypedDict, Literal
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver
class State(TypedDict):
messages: list[str]
step: int
def agent(state: State) -> State:
return {
"messages": state["messages"] + [f"step {state['step']} done"],
"step": state["step"] + 1,
}
def should_continue(state: State) -> Literal["agent", END]:
return END if state["step"] >= 3 else "agent"
graph = StateGraph(State)
graph.add_node("agent", agent)
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", should_continue)
app = graph.compile(checkpointer=MemorySaver())
result = app.invoke(
{"messages": [], "step": 0},
config={"configurable": {"thread_id": "1"}},
)
print(result)
# {'messages': ['step 0 done', 'step 1 done', 'step 2 done'], 'step': 3}
インストールは1行で済む。
pip install langgraph
invokeで最終結果を取得し、streamを使えば各superstepごとの状態変化を逐次確認できる。Agentのデバッグ時にはこのstreamがかなり便利だ。
アーキテクチャ
中核は3つの要素で構成される。
- State:グローバルな状態スキーマ。TypedDictまたはPydanticで、全ノードが読み書きする共有データ構造
- Node:純粋関数またはLangChain Runnable。シグネチャは
(state) -> dict - Edge:通常のエッジは固定遷移、条件付きエッジ(conditional_edges)はstateに応じて次のノードを決める
実行時、LangGraphは内部にPregelスタイルのsuperstepループを持っている(GoogleのPregelグラフ計算システムへのオマージュ)。各superstepでは次の処理を行う。
- 現在のstateとエッジから、このラウンドで活性化すべきノードを決める
- 実行可能なノード群を並列で走らせる(ノード関数を書く際はこの点に留意する必要がある。グローバルな順序を前提としてはいけない)
- ノードの出力はChannels機構によってStateにマージして書き戻される(並列書き込みの競合もここで処理される)
- 次のsuperstepへ進み、活性化されるノードがなくなるまで繰り返す
CheckpointはLangGraphの切り札だ。各superstepの終了時に、フレームワークが現在のstateをバックエンドへシリアライズする。
MemorySaver:メモリ上。再起動すると消える。テスト向けSqliteSaver:ローカルファイルPostgresSaver:本番運用の定番。time-travel debug にも対応
checkpointがあれば、同じthread_idを渡して再度invokeを呼ぶだけで、フレームワークが中断地点から実行を再開する。Time-travel debugはこの能力を応用したもので、過去の任意のsuperstepから再生して、当時の状態を確認できる。
Human-in-the-loopの仕組みはさらにシンプルだ。あるノードの手前にinterruptを差し込むと、そこで実行が止まり、状態を外部に公開してユーザー入力を待つ。ユーザーが応答すれば、中断地点からそのまま続行する。承認、確認、書き換えといったインタラクションパターンをLangGraphで実装するのは straightforward だ。
長所と短所
良いところ
- グラフモデルはCrewAIの「役割による協調」抽象よりも低レイヤーで、AutoGenのグループチャット抽象よりも制御しやすい。あくまでグラフであり、ノードが何で、エッジがどう流れるかは自分で決められる。
- Checkpointは本格的な本番運用に耐える品質で、Postgresバックエンドのtime-travel debugは障害調査に極めて便利。
- LangChainエコシステム(Runnable、tools、messages schema)と互換性があるが、LangChainへの依存は強制されない。
langgraphだけをインストールして使うこともできる。 - ドキュメントの品質はオープンソースフレームワークの中でもトップクラスで、公式cookbookが典型的なパターンを網羅している。
悪いところ
- 学習曲線は、LLMの薄いラッパーやシンプルなChainよりは急峻。Stateスキーマの設計を誤り、分岐条件を乱発すると、スパゲッティグラフが生まれる。ノードから十数本のエッジが伸びて、自分でも読めない状態になる。
- ローカルデバッグ時の
stream出力は冗長で、superstepごとにstateが毎回ダンプされるため、初心者は情報量に圧倒されやすい。 - 新バージョン(v0.2以降)のAPI変更が大きい。古いチュートリアルの
set_entry_pointやadd_edgeの引数順などは多くが変更されているため、そのまま写経するとエラーになる。コードを読む際は日付を確認したほうがよい。 - CrewAIの「箱出してすぐ動く」体験と比べると、LangGraphはチューリング完全なグラフマシンを渡されるようなものだ。柔軟性は高いが、Agentトポロジーの設計は自分で行う必要がある。
実際に試してみた
pip install langgraph langgraph-checkpoint-sqliteでインストールし、公式チュートリアルのReAct agentサンプルを動かした。ツール呼び出し5回分のフローを構築し、ローカルメモリ(MemorySaver)での実行時間は約12秒。
SqliteSaverに切り替えてcheckpointを有効にしたところ、同じthread_idで2回目のinvokeを呼ぶと、中断地点からそのまま再開され、0.5秒で返ってきた。この遅延差が実運用では重要になる。長時間のタスクが途中で中断したり、ネットワークが不安定だったり、リトライが必要になる場面で、ユーザーの体感は大きく変わる。
いくつかの境界ケースも試した。
StateGraph.compile()の段階でループ検出が行われ、明らかに無限ループ(自己ループ + 無条件エッジ)は止められる- ただし実際の安全弁は
max_steps設定による。条件エッジのロジックを書き間違えると、フレームワークは永遠に守ってくれるわけではない - CrewAI 0.80と同じReActタスクを比べると、起動時のオーバーヘッドはLangGraphがやや大きい(約200ms。Pregelスケジューラとcheckpoint初期化のコスト)。一方で状態の可視性と復元能力は圧倒的に高い
コミュニティで比較対象に挙がるのはAutoGen(Microsoft製、グループチャット型マルチエージェント)とLlamaIndex Workflows(イベント駆動)の2つだ。前者はより「自然言語」寄りの抽象(Agent同士がメッセージを送り合う)で、後者はより軽量。LangGraphはその中間に位置する。両者よりも厳格に構造化されている分、「プログラマーフレンドリー」でもある。
誰に向いているのか
向いているケース
- 長時間のタスク実行(多ターンのツール呼び出し、複数ステップに渡る推論)
- 人による承認が必要(金融、医療、コンプライアンスなど、AgentにHITLが必須の領域)
- セッションをまたいだ記憶が必要(チャットボット、継続学習するエージェント)
- 観測性と再生 가능성이求められる本番Agent(障害発生時に過去のcheckpointを調査できる)
向いていないケース
- 単発のQ&A:LLMを直接呼べば十分
- 使い捨てスクリプト:抽象化が過剰
- 遅延に極めて厳しい(<100ms)リアルタイムインタラクション:グラフのスケジューリングコストが許容できない
後者については、LLMの生呼び出しやLangChain Runnableで十分で、グラフの抽象を導入する意味はない。LangGraphはChainの代替ではなく、Chainでは解決できない問題が出たときの一歩先にある選択肢だ。
まとめ
LangGraphの本質は、Agentに対して明示的、永続化可能、中断可能な実行モデルを提供することにある。最も取っつきやすいフレームワークとは言えないが、本番運用に耐えるAgentを作りたい場合、特にループ・承認・長期記憶・リプレイのいずれかを必要とするケースでは、現時点で最も成熟した選択肢と言ってよい。
40k starsは伊達ではない。GitHubリポジトリはhttps://github.com/langchain-ai/langgraphで、READMEとexamples/ディレクトリからいきなり始められる。