フレームワーク

LangGraph徹底解説:有向グラフでAgentを組み立てる、40k starsの本格運用フレームワーク

Agentの実行を有向グラフとしてモデル化することで、ループ・分岐・状態の永続化・Human-in-the-loopを一つの枠組みで扱える。LangGraphは本番運用におけるAgent编排のデファクト標準になりつつある。

文字サイズ

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ステップは次のとおり。

  1. Stateを定義する(TypedDictまたはPydanticモデル)
  2. ノード関数を書く(stateを受け取り、stateの更新を返す)
  3. 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では次の処理を行う。

  1. 現在のstateとエッジから、このラウンドで活性化すべきノードを決める
  2. 実行可能なノード群を並列で走らせる(ノード関数を書く際はこの点に留意する必要がある。グローバルな順序を前提としてはいけない)
  3. ノードの出力はChannels機構によってStateにマージして書き戻される(並列書き込みの競合もここで処理される)
  4. 次の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/ディレクトリからいきなり始められる。

出典: https://github.com/langchain-ai/langgraph