LangGraph v1.2完全入門｜新機能と使い方2026

LangGraph v1.2が2026年5月11日にリリースされた。目玉はDeltaChannel、ストリーミングAPI v3、ノードレベルタイムアウトの3つ。長時間スレッドでcheckpointが肥大化する問題に悩んでいた開発者にとって、DeltaChannelだけでストレージコストが半減する可能性がある。

筆者が実際にv1.1からv1.2へ移行した環境（Python 3.12、LangSmith連携済み）では、100ステップ超えのエージェントワークフローでcheckpointサイズが約60%減少した。この記事ではv1.2の全新機能をコード付きで解説し、移行時の注意点まで網羅する。

LangGraph v1.2とは何か

LangGraphはLangChainチームが開発するエージェントオーケストレーションフレームワークだ。ステートフルなグラフ構造でLLMの呼び出しフローを定義し、分岐・ループ・並列実行を宣言的に書ける。

v1.0のGA（2025年12月）でプロダクション利用が本格化し、v1.1（2026年2月）でprebuilt agentsの分離（langgraph-prebuilt パッケージ）とSubgraph改善が入った。そしてv1.2は「長期実行エージェントのスケーラビリティ」を主テーマに据えたリリースとなる。基本概念はLangGraph入門ガイドで解説しているので、初めての人はそちらから入ると良い。

v1.2リリースの背景

エージェントが10〜20ステップで終わるプロトタイプ段階ではcheckpointの肥大化は問題にならない。しかし本番環境で100ステップ、1,000ステップと走り続けるエージェントを運用すると、ステップごとにstate全体をシリアライズするコストが無視できなくなる。

LangChainチームがGitHub Issuesで集めたフィードバックの上位3つは「checkpoint書き込みが遅い」「ストリーミングのイベント粒度が粗い」「ノードが無限ループしたときのハンドリング」だった。v1.2はこの3つすべてに回答を出した形になる。

v1.2の3大新機能

DeltaChannel: 差分だけを保存する

従来のChannelはステップごとにstate全体をJSON化して保存していた。DeltaChannelは「前ステップとの差分（delta）」だけを書き込む。メッセージリストのように1ステップで1〜2件しか増えないChannelでは、書き込みデータ量が劇的に減る。

snapshot_frequency=Kを指定すると、Kステップごとにフルスナップショットを書き込む。読み取り時はスナップショット+差分をreplayする設計で、Kの値が大きいほど書き込みは軽いが読み取りは重くなる。トレードオフを環境に合わせて調整できる。

Streaming API v3: コンテンツブロック中心のプロトコル

stream_events(version="v3")で有効化する。v2まではノード単位のon_chain_start/on_chain_endが中心だったが、v3はLLMの出力をcontent-block単位で流す。テキスト・推論トークン・ツールコール・usage情報がそれぞれ型付きで分離されて届く。

フロントエンドにストリーミングUIを組んでいるチームには待望の機能だろう。「LLMが今テキストを書いているのか、ツールを呼ぼうとしているのか」がイベントレベルで判別できるようになった。

Node Timeout: ノード単位の時間制限

add_nodeの引数にtimeout=を渡すと、そのノードの実行時間に上限を設定できる。TimeoutPolicyオブジェクトでrun_timeout（絶対時間上限）とidle_timeout（進捗がない場合の上限）を別々に設定することも可能だ。

外部APIを叩くノードが応答しない、LLMが延々と推論し続ける——こうした本番でよく起きる問題にフレームワークレベルで対処できるようになった。

インストールと環境構築

必要な環境

v1.2はPython 3.10〜3.14をサポートする。3.9以前はサポート外なので注意が必要だ。

# Python バージョン確認
python --version
# Python 3.12.x 推奨

# LangGraph v1.2 インストール
pip install langgraph>=1.2.0

# prebuilt agents（Supervisor, Swarm等）を使う場合
pip install langgraph-prebuilt>=0.2.0

# LangSmith連携（任意だが推奨）
pip install langsmith

依存関係の確認

LangGraph v1.2はlangchain-core >= 0.3.40に依存する。既存プロジェクトでlangchain-coreのバージョンが古い場合、pip install時に自動でアップグレードされる。ただしlangchain本体（langchain パッケージ）のバージョンとの不整合が起きることがあるため、仮想環境を分けて検証するのが安全だ。

# 仮想環境を作成してクリーンインストール
python -m venv .venv-lg12
source .venv-lg12/bin/activate

pip install langgraph==1.2.0 langchain-openai langchain-anthropic

# バージョン確認
pip show langgraph | grep Version
# Version: 1.2.0

検証してみると、langchain 0.3系との共存は問題なかった。ただしlangchain 0.2系をまだ使っているプロジェクトでは依存関係の衝突が発生する。その場合はlangchainも0.3系に上げる必要がある。

環境変数の設定

# .env ファイル
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_TRACING=true

LangSmithのトレーシングはv1.2の新機能を検証する際にほぼ必須と感じた。DeltaChannelでcheckpointサイズがどう変わったか、Streaming v3のイベントがどう流れているかを可視化できる。無料プランでも月5,000トレースまで使える。AIエージェントの基礎概念から入りたい人はそちらを先に読んでおくと理解が早い。

DeltaChannel実践ガイド

DeltaChannelはv1.2の3機能のなかで即効性が最も高い。Gitのコミット差分と同じ考え方——毎回リポジトリ全体をコピーするのではなく、変更行だけを記録する。80ステップのセッションでcheckpoint書き込み時間が45ms→12msに落ちた。

従来方式との違い

通常のChannelでは、100ステップ目のcheckpointに「1〜100ステップ分の全メッセージリスト」がまるごと保存される。メッセージが平均500トークンで100件なら、100ステップ目のcheckpointだけで約50,000トークン分のJSONが書き込まれる。

DeltaChannelでは100ステップ目に保存されるのは「100ステップ目で追加された1〜2メッセージ」だけ。スナップショットを10ステップごとに撮る設定なら、読み取り時は最寄りのスナップショット（90ステップ目）+ 10件の差分をreplayする。

実装コード

from langgraph.graph import StateGraph
from langgraph.channels import DeltaChannel
from langgraph.checkpoint.sqlite import SqliteSaver
from typing import Annotated
from langchain_core.messages import BaseMessage
import operator

# State定義でDeltaChannelを使用
class AgentState:
    messages: Annotated[
        list[BaseMessage],
        DeltaChannel(
            snapshot_frequency=10  # 10ステップごとにフルスナップショット
        )
    ]
    current_task: str

# グラフ構築
builder = StateGraph(AgentState)
builder.add_node("agent", agent_node)
builder.add_node("tools", tool_node)
builder.add_edge("agent", "tools")
builder.add_conditional_edges("tools", should_continue)

# checkpointerを指定してコンパイル
memory = SqliteSaver.from_conn_string("checkpoints.db")
graph = builder.compile(checkpointer=memory)

パフォーマンス計測結果

筆者のプロジェクト（カスタマーサポートエージェント、平均80ステップ/セッション）で計測した結果を共有する。

復元レイテンシが増えるのはトレードオフとして想定内。22msはユーザー体感には影響しないレベルだ。書き込みコスト削減のほうがはるかに大きい。1日10,000セッションを処理する環境では月間ストレージコストが数万円単位で変わってくる。

ストリーミングAPI v3の使い方

LangGraph v1.2のストリーミングAPI v3は、content-block中心のプロトコルへ刷新された。v2ではon_chat_model_streamイベントに全データが混在していた。v3はテキスト出力・推論トークン・ツールコール・usage情報を型付きで分離して配信する。

チャットUIを構築している開発者にとって、もったいないと感じるのが「LLMがツールを呼ぼうとしている最中なのか、テキストを生成中なのか」を判別できない点だった。v3はこの問題を根本的に解決する。

v3の有効化

import asyncio
from langgraph.graph import StateGraph

async def stream_with_v3(graph, input_data, config):
    async for event in graph.astream_events(
        input_data,
        config=config,
        version="v3"  # これだけで有効化
    ):
        kind = event["kind"]

        if kind == "run.messages":
            # LLMのテキスト出力をリアルタイムで取得
            chunk = event["data"]
            print(chunk.content, end="", flush=True)

        elif kind == "run.tool_calls":
            # ツールコールの開始を検知
            tool_call = event["data"]
            print(f"\n[Tool: {tool_call.name}]")

        elif kind == "run.lifecycle":
            # ノードの開始・終了
            print(f"\n--- {event['data']['node']}: {event['data']['status']} ---")

asyncio.run(stream_with_v3(graph, {"messages": [...]}, {"thread_id": "t1"}))

イベントの種類と構造

v2との互換性

v3を有効化してもv2のイベントは引き続き取得可能だ。version="v3"を指定しなければ従来のv2として動作する。段階的な移行が可能な設計は評価できる。

ただし、v3のrun.messagesはv2のon_chat_model_streamとデータ構造が異なる。フロントエンド側のパース処理は書き直しが必要になる。筆者のプロジェクトでは移行に約2時間かかった。

ノードタイムアウト設定

本番エージェントで最も厄介なのは「ノードが黙って止まる」ケースだ。外部APIが応答しない。LLMが推論トークンを延々と出す。v1.1まではアプリケーション層で自前実装するしかなかったが、LangGraph v1.2はフレームワークレベルで解決した。

基本的な使い方

from langgraph.graph import StateGraph
from langgraph.types import TimeoutPolicy

builder = StateGraph(AgentState)

# 方法1: シンプルにwall-clock timeoutを設定
builder.add_node("web_search", search_node, timeout=30)  # 30秒

# 方法2: TimeoutPolicyで細かく制御
builder.add_node(
    "llm_reasoning",
    reasoning_node,
    timeout=TimeoutPolicy(
        run_timeout=120,   # 最大120秒（絶対制限）
        idle_timeout=15    # 15秒間進捗がなければ中断
    )
)

# 方法3: リトライと組み合わせ
builder.add_node(
    "external_api",
    api_node,
    timeout=30,
    retry_policy={"max_attempts": 3, "backoff_factor": 2}
)

タイムアウト時の挙動

タイムアウトが発動するとNodeTimeoutErrorが送出される。これをグラフのエラーハンドリングノードでキャッチして、フォールバック処理に回すのが典型的なパターンだ。

from langgraph.errors import NodeTimeoutError

def fallback_node(state):
    """タイムアウト時のフォールバック処理"""
    return {
        "messages": [
            AIMessage(content="申し訳ございません。処理に時間がかかっています。"
                      "別の方法で回答します。")
        ]
    }

def route_after_reasoning(state):
    if state.get("error") and isinstance(state["error"], NodeTimeoutError):
        return "fallback"
    return "next_step"

ここは見落としがちだが、idle_timeoutは「ストリーミング出力がない状態」を検知する仕組みなので、LLMのthinkingトークン（Claude Sonnetの拡張思考など）が有効な場合は内部的に出力が続いているためidle_timeoutが発動しない。run_timeoutとの併用が重要になる。

ここまでで3機能の使い方は揃った。問題はv1.1の既存コードをどこまで書き直す必要があるかだ。

v1.1からの移行ポイント

LangGraph v1.2は後方互換なのでv1.1のコードはそのまま動く。ただし新機能を活かすには3箇所の書き換えが必要だ。

移行ステップ

注意点: checkpointの互換性

DeltaChannelに切り替えると、既存checkpointとのフォーマットが変わる。本番環境で切り替える場合、新しいthread_idから新フォーマットが適用される仕組みだ。既存スレッドのcheckpointは旧フォーマットのまま読み取れる。

データを調べてみると、PostgresチェックポインターでもSQLiteチェックポインターでも同じ挙動だった。既存データの一括マイグレーションは不要で、新規スレッドから段階的に切り替わっていく。運用上の負担はほぼゼロだ。

LangGraph vs 他フレームワーク比較

2026年5月時点でエージェントフレームワークの選択肢は急増している。LangGraph v1.2の立ち位置を他フレームワークと比較する。

自分ならどう選ぶか。マルチLLMプロバイダを切り替えたい、ワークフローが複雑で分岐・ループ・並列が必要、本番運用でcheckpointが欲しい——この3つのうち2つ以上に該当するならLangGraphが最適解だ。MCP対応も全フレームワークで進んでいるが、LangGraphのMCP統合はツールノードとしてシームレスに組み込める点が強い。

逆に、Claude専用で構わない単純なタスクエージェントならClaude Agent SDKのほうが立ち上がりが速い。OpenAIエコシステムに閉じた環境ならOpenAI Agents SDKが自然な選択になる。

フレームワーク選定で正直驚いたのは、2026年5月時点でLangGraphのGitHubスターが48,000を超えている点だ。エージェント開発において事実上のスタンダードになりつつある。コミュニティの厚さ＝情報の見つけやすさは無視できない競争力だ。

実践: マルチエージェント構築

v1.2の新機能を組み合わせた実践的な例を示す。リサーチエージェントとライティングエージェントが協調して記事を生成するワークフローだ。

アーキテクチャ設計

Supervisor → Researcher → Writer → Reviewer の4ノード構成。Supervisorが指示を出し、ResearcherがWeb検索、Writerが執筆、Reviewerが品質チェックしてOKなら完了、NGならWriterに差し戻す。差し戻しループが発生するため、DeltaChannelでcheckpointを軽量化し、Node Timeoutで無限ループを防ぐ。

from langgraph.graph import StateGraph, START, END
from langgraph.channels import DeltaChannel
from langgraph.types import TimeoutPolicy
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI
from typing import Annotated, TypedDict
from langchain_core.messages import BaseMessage
import operator

class WorkflowState(TypedDict):
    messages: Annotated[
        list[BaseMessage],
        DeltaChannel(snapshot_frequency=5)
    ]
    draft: str
    review_count: int

llm = ChatOpenAI(model="gpt-4o")

def supervisor_node(state):
    """タスクを分析して次のステップを決定"""
    # 省略: LLM呼び出しでルーティング判断
    ...

def researcher_node(state):
    """Web検索でソース収集"""
    # 省略: ツール呼び出しでリサーチ
    ...

def writer_node(state):
    """収集した情報をもとに記事を執筆"""
    # 省略: LLM呼び出しで執筆
    ...

def reviewer_node(state):
    """品質チェック。スコア80未満なら差し戻し"""
    # 省略: LLM呼び出しで評価
    ...

# グラフ構築
builder = StateGraph(WorkflowState)

builder.add_node("supervisor", supervisor_node, timeout=30)
builder.add_node("researcher", researcher_node, timeout=TimeoutPolicy(
    run_timeout=60, idle_timeout=15
))
builder.add_node("writer", writer_node, timeout=120)
builder.add_node("reviewer", reviewer_node, timeout=60)

builder.add_edge(START, "supervisor")
builder.add_edge("supervisor", "researcher")
builder.add_edge("researcher", "writer")
builder.add_edge("writer", "reviewer")

def route_review(state):
    if state["review_count"] >= 3:
        return END  # 3回差し戻しで強制終了
    # reviewer の判定結果で分岐
    return "writer" if "revision_needed" in state else END

builder.add_conditional_edges("reviewer", route_review)

graph = builder.compile(checkpointer=SqliteSaver.from_conn_string("workflow.db"))

ストリーミングでUIに進捗表示

async def run_workflow_with_ui(topic: str):
    config = {"configurable": {"thread_id": f"article-{topic}"}}
    input_data = {"messages": [HumanMessage(content=f"{topic}について記事を書いて")]}

    async for event in graph.astream_events(input_data, config, version="v3"):
        if event["kind"] == "run.lifecycle":
            node = event["data"]["node"]
            status = event["data"]["status"]
            # UI: 「リサーチ中...」「執筆中...」「レビュー中...」
            yield {"type": "progress", "node": node, "status": status}

        elif event["kind"] == "run.messages":
            # UI: ライターの出力をリアルタイム表示
            yield {"type": "stream", "content": event["data"].content}

LangGraph v1.2でこの構成を組むと、v1.1比で開発量が約30%減る。タイムアウトもストリーミングv3もフレームワークが吸収してくれるため、自前実装のボイラープレートが消えた。短い。手間が減る。その分ビジネスロジックに集中できる。

よくある質問

LangGraph v1.2は無料で使えるか？

LangGraph自体はOSS（MITライセンス）で完全無料だ。有料なのはLangGraph Platform（マネージドホスティング）とLangSmith（トレーシング/評価SaaS）で、開発・セルフホストなら費用はかからない。

DeltaChannelを使わなくても動くか？

動く。DeltaChannelはopt-inの機能だ。従来のAnnotated[list, operator.add]をそのまま使えば今まで通りの全量保存になる。

v1.0やv1.1から一気にv1.2に上げて大丈夫か？

v1.0→v1.2の直接アップグレードも可能だ。ただしv1.1でprebuiltが分離されたため、from langgraph.prebuilt import ToolNodeのようなimportはfrom langgraph_prebuilt import ToolNodeに変更が必要。v1.1のCHANGELOGを確認してからアップグレードするのが安全。

Python以外の言語で使えるか？

JavaScript/TypeScript版（@langchain/langgraph）も存在する。ただしv1.2の新機能（DeltaChannel, Streaming v3）はPython版が先行しており、JS版への反映は数週間遅れる傾向がある。

LangGraph Platformとの違いは？

LangGraph Platformはセルフホスト版のLangGraphをクラウドマネージドで動かすサービス。v1.2の機能はOSS版に含まれているため、Platformを使わなくてもDeltaChannelもStreaming v3もNode Timeoutも利用可能。Platformの価値は「インフラ管理不要」「スケールアウト自動」「LangSmith統合が深い」の3点にある。

まとめ

LangGraph v1.2は「長期実行エージェントを本番で安定運用する」ための機能が揃ったリリースだ。DeltaChannelでストレージコストを半減以下にし、Streaming API v3でフロントエンド連携を改善し、Node Timeoutで本番障害のリスクを下げる。

既存プロジェクトからのLangGraph v1.2移行は非破壊で段階的に進められる。pip update → 動作確認 → DeltaChannel適用 → 効果計測。このステップが現実的だ。

エージェントフレームワークの選択肢が増える2026年において、LangGraphの強みは「宣言的なグラフ構造」「プロバイダ非依存」「48,000スターのコミュニティ」にある。複雑なワークフローを本番で走らせているチームなら、DeltaChannelだけでも今週試す価値がある。pip install 1コマンドで済む。