LangGraph入門｜とは？状態遷移でマルチエージェントを作る基本とLangChainとの違い・比較

AIエージェントを「とりあえず動かす」段階を超えると、必ずぶつかるのがループ・分岐・人間の承認・障害からの復旧をどう設計するかという問題です。LangGraphとは、LLMエージェントをノード・エッジ・状態からなるステートマシンとして組むOSSフレームワークで、この設計問題に一次ソースで答える存在です。本記事はLangGraph入門として、最小コードから本番運用まで整理します。

9種のAIエージェントフレームワークをStar数・実コードで横断比較した AIエージェントフレームワーク比較2026｜LangGraph・CrewAI・Dify等9種をStar数・実コードで検証 を先に読むと、LangGraphが数あるフレームワークの中でどの位置にいるか俯瞰できます。

要点まとめ｜LangGraphとは何か

LangGraphは「魔法の自律エージェント」を約束するフレームワークではありません。むしろ逆で、エージェントの挙動を状態遷移図として開発者が支配するための道具です。LLMの非決定性を、グラフという決定的な骨格の中に閉じ込める。この発想が、本番投入できるエージェントとデモ止まりのエージェントを分けます。

背景と文脈｜なぜ今LangGraph入門が必要か

LangGraphは公式README（langchain-ai/langgraph）で「長時間動くステートフルなエージェントを構築・管理・デプロイするための低レベルなオーケストレーションフレームワークおよびランタイム」と説明されています。KlarnaやReplit、Elasticといった企業が本番で採用していると公表されており、デモではなく実運用を前提に設計されている点が特徴です。「エージェントの本番運用」という言葉が指す中身は、単発のチャットボット応答ではなく、数分〜数時間かけてツールを往復し、途中で人間の承認を挟み、失敗すれば途中から再開する、といった長時間ワークフローを指します。この規模のワークフローを素のPythonスクリプトで書くと、状態管理・リトライ・ロギングがコードの至る所に散らばり、半年後に誰も全体像を追えなくなる。LangGraphはこの散らばりを、グラフという1つの構造に集約します。

よくある混乱が「LangChainとLangGraphはどう違うのか」です。両者は競合ではなく階層が異なります。

・LangChain：モデル・ツール・エージェントループの抽象化と、各種サービスへの連携（インテグレーション）を提供する高レベルのフレームワーク
・LangGraph：その下で動く低レベルの実行ランタイム。耐久的な実行（durable execution）・ストリーミング・human-in-the-loop・永続化を担う
・両者の関係：LangChainの新しいエージェント抽象はLangGraphの上に構築されている。ただし公式は「LangGraphを使うのにLangChainは必須ではない」と明言しており、LangGraphは単体でも利用できる

この誤解が生まれやすいのは、両方とも同じlangchain-ai組織が開発しているためです。パッケージとしてもlangchainとlanggraphは別物で、pip install langgraphだけでStateGraphは動きます。LangChainの各種インテグレーション（モデルプロバイダ・ベクトルストア・ツールの共通インターフェース）を併用するかどうかは、プロジェクトごとに独立して選べます。

つまりLangGraphは、特定のモデルや上位フレームワークに縛られない「エージェントの実行基盤」として位置づけられます。公式は同じエコシステム上で、より高レベルにプランニング・サブエージェント・ファイルシステム操作を扱うDeep AgentsというLangGraph上位パッケージも提供しており、「まず速く動かしたいならDeep Agents、制御を自分で書きたいならLangGraph本体」という選び分けが公式ドキュメント上でも案内されています。

LangGraphが解くのは、素のLLM呼び出し（単純なプロンプト→応答の1往復）では扱いにくい4つの難所です。

・ループ：ツールを呼んで結果を見て、また考える、を条件が満たされるまで繰り返す
・分岐：LLMの出力に応じて次に進む先を動的に切り替える
・耐久性：途中でノードが失敗しても、最後に成功したステップから再開する（プロセスクラッシュやデプロイの再起動をまたいでも状態は消えない）
・介在：危険な操作の前で実行を止め、人間の承認を待ってから続行する

これらを「フレームワークの隠れた挙動」ではなく、開発者が書いたグラフの構造として表現できる。これがLangGraph入門でまず押さえるべき設計思想です。PyPIの月間ダウンロード数は約71.6M回（2026年8月11日実測・pypistats.org）に達しており、エコシステムと運用ノウハウの蓄積という点でも厚みがあります。

詳しく見ていく｜4つの構成要素と最小コード

LangGraphのアーキテクチャは、4つの構成要素に分解できます。

・State（状態）：グラフ全体で共有される型付きのデータ。PythonではTypedDict、TypeScriptではAnnotationで定義する
・Node（ノード）：状態を受け取り、状態の更新（差分）を返す関数。LLM呼び出しやツール実行を担う
・Edge（エッジ）：ノード間の遷移。固定のエッジと、状態に応じて行き先を変える条件付きエッジ（Conditional Edges）がある
・Reducer（リデューサ）：状態を更新するときの合成方法。たとえばメッセージ履歴は「上書き」ではなく「追記」したいのでoperator.addを指定する

冒頭のMermaid図はこの4要素を使った最小のReActループ（LLMが考え→ツールを呼び→結果を見て→また考える）です。llm_callからtool_nodeへ進むか終了するかを条件付きエッジが決め、tool_nodeからは無条件でllm_callに戻る。この「戻り」のエッジがループを作ります。素のコードでwhileを書く代わりに、グラフの形そのものが制御フローになっているのが分かります。

インストールから始めます。LangGraphはPython版とTypeScript版（LangGraph.js）の両方が提供されています。

# Python
pip install -U langgraph langchain "langchain[anthropic]"

# TypeScript / JavaScript
npm install @langchain/langgraph @langchain/core @langchain/anthropic

最短で動かすなら、公式のprebuilt create_react_agent を使うのが入門の近道です。状態もエッジも自分で書かずに、ツールを渡すだけでReActエージェントが立ち上がります。

from langgraph.prebuilt import create_react_agent

def get_weather(city: str) -> str:
    """指定した都市の天気を返す。"""
    return f"{city} は晴れ、22度です。"

agent = create_react_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[get_weather],
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "東京の天気は？"}]}
)
print(result["messages"][-1].content)

制御フローを自分で支配したくなったら、StateGraphに降ります。次は同じReActループを状態・ノード・条件付きエッジで明示的に組み、さらにチェックポインタで永続化まで一気通貫させた例です。

from typing import Literal
from typing_extensions import TypedDict, Annotated
import operator
from langchain.chat_models import init_chat_model
from langchain.tools import tool
from langchain.messages import AnyMessage, SystemMessage, ToolMessage, HumanMessage
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver

model = init_chat_model("claude-sonnet-4-6", temperature=0)

@tool
def add(a: int, b: int) -> int:
    """a と b を足す。"""
    return a + b

tools = [add]
tools_by_name = {t.name: t for t in tools}
model_with_tools = model.bind_tools(tools)

# 状態: messages は「追記」したいので operator.add をリデューサに指定
class State(TypedDict):
    messages: Annotated[list[AnyMessage], operator.add]

def llm_call(state: State):
    return {"messages": [model_with_tools.invoke(
        [SystemMessage(content="あなたは算術を行うアシスタントです。")] + state["messages"]
    )]}

def tool_node(state: State):
    result = []
    for call in state["messages"][-1].tool_calls:
        obs = tools_by_name[call["name"]].invoke(call["args"])
        result.append(ToolMessage(content=obs, tool_call_id=call["id"]))
    return {"messages": result}

def should_continue(state: State) -> Literal["tool_node", "__end__"]:
    return "tool_node" if state["messages"][-1].tool_calls else END

builder = StateGraph(State)
builder.add_node("llm_call", llm_call)
builder.add_node("tool_node", tool_node)
builder.add_edge(START, "llm_call")
builder.add_conditional_edges("llm_call", should_continue, ["tool_node", END])
builder.add_edge("tool_node", "llm_call")

# checkpointer=InMemorySaver() で状態を thread_id ごとに自動保存する
# 本番は PostgresSaver、ローカルは SqliteSaver に差し替える
graph = builder.compile(checkpointer=InMemorySaver())

config = {"configurable": {"thread_id": "user-123"}}
out = graph.invoke({"messages": [HumanMessage(content="3 と 4 を足して。")]}, config)
for m in out["messages"]:
    m.pretty_print()

# 同じ thread_id で続けると、前回の状態（会話メモリ）が引き継がれる
graph.invoke({"messages": [HumanMessage(content="その結果に10を足して")]}, config)

TypeScript（LangGraph.js）でも、Annotationによるスキーマ定義とStateGraphでほぼ同じ概念のままグラフを書けます。状態の合成方法をスキーマ側で宣言する点がPython版との主な違いです。詳細は姉妹記事の AIエージェントとは？仕組み・種類・代表的OSSフレームワークを初心者向けに解説【2026年版】 でも扱っているので、そもそもエージェントの基礎から押さえたい場合はあわせて参照してください。

アーキテクチャと仕組み｜LangGraphのステートマシンとスーパーステップ

LangGraphの実行は「スーパーステップ」という単位で進みます。1スーパーステップは、その時点でスケジュールされた全ノードを（並列に動くこともある）一度に実行する1ティックです。各スーパーステップの境界でチェックポイント（状態のスナップショット）が保存され、ここが障害復旧やタイムトラベルの起点になります。LangGraphが「単なるグラフ実行器」ではなく本番エージェント基盤と呼べるのは、このスーパーステップ単位の永続化があるからです。

Checkpoint（永続化）：compile(checkpointer=...)でチェックポインタを差し込むと、各ステップの状態がthread_idごとに自動保存されます。会話メモリ、障害からの再開、過去状態への巻き戻し（タイムトラベル）がこれ一つで実現します。開発用のInMemorySaver、ローカル用のSqliteSaver、本番用のPostgresSaverが用意されており、いずれもBaseCheckpointSaverという共通インターフェースに従います。スレッド（会話）をまたいで情報を共有したい場合は、別途Storeインターフェースで名前空間付きの長期メモリや意味検索を扱えます。thread_idに閉じた短期の作業記憶（Checkpoint）と、ユーザーをまたぐ長期記憶（Store）を分けて設計するのが公式の推奨パターンです。

Human-in-the-loop（人間の介在）：interrupt()で実行を止め、Command(resume=...)で再開します。危険な操作の前に人間の承認を挟む典型的なゲートが数行で書けます。チェックポインタが有効であることが前提で、停止中の状態はthread_idに紐づいて保存されるため、別プロセス・別時刻からでも安全に再開できます。

Streaming（ストリーミング）：エージェントは応答までに何度もLLMとツールを往復するため、graph.stream(...)で実行中の状態や出力を逐次受け取れます。stream_modeで粒度を切り替えられ、"values"なら各ステップ後の状態全体、"updates"なら各ノードが返した差分だけ、"messages"ならLLMのトークン単位の出力を流せます。チェックポイントと組み合わせれば、途中で止めて再開しても続きからストリーミングを再開できます。ユーザー体験としては「今どのノードを処理しているか」を画面に逐次表示したり、最終回答をトークン単位でタイプライター表示したりする用途に直結します。

他の選択肢との比較｜CrewAI・AutoGen・Mastraとの違い

「どれを選ぶか」は、制御の厳密さ・言語・モデルの3軸でほぼ決まります。2026年時点の主要フレームワークを整理します。

選び方の目安を言葉にすると次のとおりです。

・作業が自然に「役割」に分かれ、午後いっぱいで動くプロトタイプが欲しい → CrewAI
・1つのワークフローにループ・分岐・リトライ・耐久的チェックポイント・人間承認が必要 → LangGraph
・バックエンドがTypeScriptで、エージェント・ツール・メモリ・RAG・評価を1スタックで完結させたい → Mastra
・OpenAIモデル中心で軽量に組みたい → OpenAI Agents SDK
・研究目的でエージェント同士の自由な会話パターンを試したい → AutoGen/AG2（ただし本番採用は前述の通り減少傾向）

なおAutoGenはMicrosoftのSemantic Kernelと統合後、独立プロジェクトAG2として分岐しました。更新は続いていますが本番採用は減少傾向で、多くのチームがLangGraphやCrewAIへ移行したと報じられています。

比較の軸として見落とされがちなのが「学習コストの中身」です。CrewAIは役割とタスクをYAML・デコレータ的な書き方で宣言すれば動くため、最初の1本を書く速度はLangGraphより速いことが多い一方、宣言的な分だけ「なぜその順番で実行されたか」を追いにくい場面があります。LangGraphは逆に、最初の1本を書くまでの概念（State・Node・Edge・Reducer）を覚える必要がある代わりに、実行順序そのものがコードに書いてあるため後から読んでも追いやすい、というトレードオフです。トークン消費そのものを削る設計は AIエージェントのトークン最適化ガイド2026 を、本番品質へ引き上げる設計原則は 12-Factor Agents完全解説 を併せて参照すると、この記事だけでは拾いきれない周辺論点まで見渡せます。

実務への影響｜LangGraph本番運用のチェックリスト

エージェントはループと分岐で挙動が見えづらく、「なぜこの出力になったか」を後から追えないと運用が破綻します。デモの段階では気にならなかった「何回LLMを呼んだか」「どのノードで失敗したか」が、本番トラフィックの規模になった途端にコストと信頼性の両方を左右する変数になります。LangGraphの本番運用では、観測と永続化を最初から組み込むのが定石です。

・観測：LangSmithでトレースを取り、どのノードで何回LLMを呼んだか・どこで失敗したかを可視化する
・永続化：本番ではPostgresSaverでチェックポイントを外部DBに保存する。プロセスが落ちてもthread_idから再開でき、会話メモリも維持される
・デプロイ：チェックポインタを外部ストレージにすればステートレスなワーカーとしてスケールできる。状態はDB側に持たせ、アプリは水平にスケールアウトする設計が基本
・コスト管理：再帰制限（recursion_limit）とLLM呼び出し回数の監視を初期から入れる。条件付きエッジのバグはそのままAPI課金の暴走になる

公式はLangSmith Deploymentという名称で「長時間動くステートフルなワークフロー向けに設計されたデプロイ基盤」も提供しています。チームでグラフを発見・再利用・設定・共有し、LangSmith Studioでビジュアルにプロトタイピングしながら反復できる、と公式ドキュメントに明記されています。自前でスケーリング基盤を組む前に、まずこの標準デプロイ経路で十分かを検討する価値があります。

観測まわりのAPIは実は今も動いています。GitHub上のPRタイムスタンプを実測すると、2026年7月21日の同日中にadd_nodeへtrace_policyを指定できるようにする変更（#8362）が入り、その直後にTracePolicyからタグが外され（#8402）、さらに一度追加された削除がリバートされる（#8403）という往復があり、APIが固まりきっていない状態でした。それから3週間後、本日2026年8月11日リリースの1.2.11でadd_nodeへのtrace_policy公開が改めて正式に取り込まれています（#8523、作成2026年8月4日）。トレース制御に依存する実装は、この経緯を踏まえてバージョンを固定してから設計に組み込むのが確実です。

入門を終えて次に効く、運用寄りの実践Tipsをまとめます。

・状態は小さく保つ。グラフ全体で共有される状態に何でも詰め込むと、ノード間の依存が見えなくなる。ノード固有の作業データはローカルに留める
・リデューサを意識する。メッセージはoperator.addで追記、それ以外のキーはデフォルトで上書き。並列ノードがある場合は特に「合成方法」を先に決める
・再帰制限を設定する。条件付きエッジのバグでループが止まらない事故を防ぐため、config={"recursion_limit": N}で上限を決めておく
・チェックポインタは開発の最初から入れる。後付けすると会話メモリやデバッグの設計をやり直すことになる
・グラフを可視化する。graph.get_graph().draw_mermaid()でMermaid図を出力でき、レビューやドキュメント化に役立つ
・状態に巨大データを詰めない。大きなファイルやベクトルは状態ではなく外部ストアに置き、参照だけを持つ

外部入力を扱うエージェントでは、プロンプトインジェクション対策も忘れてはいけません。危険なツールの前にinterrupt()で人間承認を挟む、外部テキストとシステム指示を分離する、といった多層防御が前提です。

まとめ｜LangGraph入門の次の一歩

LangGraphは、AIエージェントの「ループ・分岐・耐久性・介在」という4つの難所を、グラフという決定的な骨格で開発者に取り戻させるオーケストレーション基盤です。最初はcreate_react_agentで1本動かし、制御フローを自分で支配したくなったらStateGraphへ降りる。チェックポインタと観測（LangSmith）を最初から入れておけば、デモから本番までの距離は思ったより短くなります。CrewAIやMastraとの違いは「制御の厳密さをどこまで自分で持ちたいか」で選べば迷いません。まずは冒頭のMermaid図と最小コードを手元で動かし、状態・ノード・エッジ・条件分岐の4概念を体で覚えるのがLangGraph入門の最短ルートです。そこから先は、比較表で挙げたCrewAI・Mastra・OpenAI Agents SDKのいずれかと実際に見比べ、自分のワークフローがどれだけ「制御の厳密さ」を必要としているかを測るのが次の一歩になります。

参照ソース

• LangGraph GitHubリポジトリ（langchain-ai/langgraph）
• LangGraph 公式ドキュメント（docs.langchain.com）
• LangGraph クイックスタート
• LangGraph 永続化（Persistence）ガイド
• langchain-ai/langgraph リリース 1.2.11（2026-08-11）
• PR #8362「expose trace_policy on add_node」（2026-07-21マージ）
• PR #8402「drop tags from TracePolicy」（2026-07-21マージ）
• PR #8403「revert: delete TracePolicy」（2026-07-21マージ）
• PR #8523「expose trace_policy on add_node」（2026-08-11マージ）