LangGraphでAIエージェントを構築する：ステップバイステップのチュートリアル

LangGraphは、ステートフルなAIエージェントを、ノードとエッジの明示的なグラフとして構築するためのLangChainの低レベルフレームワークです。agentがどのように分岐し、一時停止し、長時間にわたるタスクの間で状態を保持するかを、直接コントロールできます。業務に条件ロジック、複数ステップの承認フロー、1回の会話ではなく何日も持続するメモリが必要になったときに、チームが選ぶコードベースの選択肢です。このガイドでは、LangGraphとは何か、インストール方法、2つの動作例を含む構築手順の全体像、そして他の選択肢と比べてどんなときに適しているかを解説します。

LangGraphとは何か

LangGraphは、長時間稼働するステートフルなagentを構築、管理、デプロイするための、低レベルのオーケストレーションフレームワークでありランタイムです。LangChainの高レベルな抽象化とは別のものです。LangChainはモデル、ツール、構築済みのagentパターンを提供し、LangGraphはその下にあるグラフベースのランタイムを提供します。そこでは、ノードを計算ステップ、エッジをそれらの間の経路、そして実行全体を流れる共有のステートオブジェクトとして定義します。これは意図的な設計です。細かい制御が不要なときは妥当なデフォルトを使い、必要なときは明示的なグラフを使います。

実際の本番利用が、その売り文句を裏づけています。LangGraphの本番利用についてのLangChain自身の記事では、本番利用企業として、Uber(開発者プラットフォームでの大規模なコード移行)、LinkedIn(候補者のソーシングとメッセージ送信を自動化するAIリクルーター)、Replit(ヒューマンインザループのレビューを備えたマルチエージェントシステム)、Elastic(リアルタイムの脅威検知のためにagentのネットワークを統括)が挙げられています。同じくLangGraphで構築されたAppFolioの不動産管理コパイロットは、不動産管理者の作業時間を週10時間以上削減し、意思決定の精度を2倍にしました。漠然とした導入の主張ではなく、具体的な成果です。

こうしたデプロイは、例外ではなく標準になりつつあります。Gartnerは、2026年末までにエンタープライズアプリケーションの40%にタスク特化型AIエージェントが搭載されると予測しています(2025年は5%未満)。この変化のかなりの部分は、LangGraphのようにマルチエージェントシステム専用に作られたフレームワークで起きています。グラフを使えば、ひとつのモデルがすべてを一度に処理するのではなく、オーケストレーターが複数の専門ノードに作業を渡す構造をモデル化できます。

LangGraphの用語と6つの構成要素の対応

AIエージェントの構築方法をお読みであれば、すべてのagentに必要な6つの構成要素はご存じのはずです。役割、ツール、ルール、シナリオプレイブック、意思決定ロジック、ガードレールです。LangGraphでは、それぞれがコード上に具体的な居場所を持っています。

ここに概念的にLangGraph固有のものはありません。LangGraphが加えるのは、ブラックボックスのループではなく、明示的で検査可能なグラフです。これはまさに、業務のロジックが本当にカスタムになってきたら求めるべき種類の制御だと、no-codeとコードのAIエージェントで解説されています。

LangGraphのインストール

pip install -U langgraph langchain

langgraphは、コアとなるグラフとランタイムのライブラリです。langchainは、標準的なツール呼び出しagentのための現在の高レベルなエントリーポイントであるcreate_agentを追加します。これは内部でLangGraphの上で動作します。モデルプロバイダーのAPIキーを環境変数に設定すれば、構築を始められます。

最短ルート：create_agent

モデル、いくつかのツール、system promptだけが必要な単一のagentであれば、グラフを直接扱う必要はありません。

from langchain.agents import create_agent

def get_account_status(company: str) -> str:
    """Look up a customer account's status by company name."""
    return f"{company}: active, plan tier Growth, renewal in 45 days."

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[get_account_status],
    system_prompt="You are a support assistant. Answer only from tool results, never guess.",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the status of Acme Corp's account?"}]}
)
print(result["messages"][-1].content)

これは、あらゆるプラットフォームが頼りにしているAIエージェントはどのようにツールを使うかと同じ仕組みです。関数を記述し、いつ呼び出すかをモデルに判断させ、結果を戻します。create_agentは、LangGraphの旧来のcreate_react_agentヘルパーに代わる推奨の出発点です。考え方は同じで、APIがすっきりしました。

より低レベルへ：条件付きルーティングを備えたカスタムグラフ

最短ルートで多くのことはカバーできますが、「Xを実行し、リスクが検出された場合のみ人間のレビューステップに分岐する」といった流れは表現できません。そのためには、グラフを直接構築します。ここでは、AI契約レビューエージェントのブループリントに近い、簡略化した契約レビューのフローを紹介します。契約を分析し、分析結果に応じて人間のレビュアーに回すか、自動承認するかを振り分けます。

from typing import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver

class ReviewState(TypedDict):
    contract_text: str
    risk_flagged: bool
    summary: str

def analyze_contract(state: ReviewState) -> dict:
    # call the model here to extract terms and set risk_flagged
    return {"risk_flagged": True, "summary": "Non-standard liability cap on page 4."}

def route_on_risk(state: ReviewState) -> str:
    return "human_review" if state["risk_flagged"] else "auto_approve"

def human_review(state: ReviewState) -> dict:
    return {"summary": state["summary"] + " Routed to legal for review."}

def auto_approve(state: ReviewState) -> dict:
    return {"summary": state["summary"] + " Auto-approved, no flags."}

graph = StateGraph(ReviewState)
graph.add_node("analyze", analyze_contract)
graph.add_node("human_review", human_review)
graph.add_node("auto_approve", auto_approve)

graph.add_edge(START, "analyze")
graph.add_conditional_edges("analyze", route_on_risk, {
    "human_review": "human_review",
    "auto_approve": "auto_approve",
})
graph.add_edge("human_review", END)
graph.add_edge("auto_approve", END)

app = graph.compile(checkpointer=InMemorySaver())

add_conditional_edgesは、意思決定ロジックの構成要素をそのままコードにしたものです。analyzeの実行後、route_on_riskがステートを調べ、名前の付いた2つの経路のどちらかへ実行を送ります。これは、単一の直線的なツール呼び出しループでは表現しきれない分岐であり、マルチエージェントシステムや複数ステップの承認フローが関わってくると、チームがLangGraphを選ぶ理由になります。

永続化とメモリ

compile()のcheckpointer引数が、グラフをステートレスではなく再開可能にします。上記のInMemorySaverはローカルでのテストには十分ですが、プロセスを再起動すると消えます。本番のグラフでは、代わりに永続的なバックエンドを使います。SQLiteやPostgresのチェックポイントセーバーは、別途インストールできるパッケージとして提供されており、thread_idをキーにすることで、特定の実行のステートを数日後に再読み込みして続行できます。これは、AIエージェントのメモリで一般論として解説している、ワーキングメモリと永続メモリの区別と同じです。checkpointerは、永続メモリに対するLangGraphの具体的な答えです。

interruptによるヒューマンインザループ

LangGraphのinterrupt()関数は、特定の時点でグラフの実行を一時停止し、再開前に外部からの入力を待ちます。上記のhuman_reviewノードが、プレースホルダーのロジックではなく本番の実装で必要とするのは、まさにこれです。人間(または別のシステム)が一時停止したステートをレビューして応答すると、グラフは最初からやり直すのではなく、チェックポイントされたステートを使って、まさにその地点から再開します。これは、AIエージェントのヒューマンインザループで一般論として解説している承認ゲートの具体的な仕組みです。人間がいつ介入すべきかをグラフが推測するのではなく、その判断をルーティングロジックに直接組み込みます。

公開前のガードレールとテスト

条件付きエッジの品質は、どちらにルーティングするかを決めるロジックの品質次第です。そのため、実際の契約、チケット、レコードに触れる前に、そのロジックを検証してください。モデルの判断だけに頼らず、ノード内に明示的なチェックを加えます(自分で定義したルールに違反した出力を却下または再試行します)。これは、AIエージェントのガードレールで解説している原則です。また、クリーンなテスト実行が1回成功しただけで、グラフが完成したとは言えません。AIエージェントの評価とテスト方法では、LangGraphのagentが本番の処理量に触れる前に、人間のレビューに回すべき複雑なケースも含めて、過去のケースから実際のテストセットを作る方法を解説しています。

コストと制限

LangGraph自体は無料のオープンソースです。支払うのはLLMのAPI利用料で、ノードと分岐が多いグラフは、同じ業務をこなす適切にスコープされた単一のagentよりも多くのモデル呼び出しを行います。これはマルチエージェントシステムで解説しているトレードオフと同じです。グラフを自分でホストして監視したくない場合、LangChainはLangGraph Platformも提供しています。永続化とオブザーバビリティが組み込まれた、有料のホスト型デプロイのオプションです。自分で運用する場合は、自社のインフラとモデル呼び出し以外にコストはかかりません。

本当の制約は価格ではありません。LangGraphにはビジュアルビルダーも、構築済みのアプリコネクタもないという点です。すべての連携、すべてのリトライポリシー、すべてのエラー処理を、コードで書く必要があります。これは、no-codeプラットフォームの限られたロジックに対して、グラフが与えてくれる制御と引き換えになるものです。

LangGraphと代替ツールの選び方

Key Facts

• LangGraphは、ステートフルなagentのための低レベルのオープンソースのオーケストレーションフレームワークでありランタイムです。LangChainの高レベルな抽象化とは別のものですが、補完関係にあります。
• 本番利用が確認されている企業には、Uber、LinkedIn、Replit、Elasticがあります。AppFolioがLangGraphで構築したコパイロットは、不動産管理者の作業時間を週10時間以上削減し、意思決定の精度を2倍にしました。
• langchainパッケージのcreate_agentが、現在推奨される高レベルのエントリーポイントで、旧来のcreate_react_agentヘルパーに代わるものです。LangGraphの上で動作します。
• add_conditional_edgesを備えたStateGraphによって、agentは自身の出力に基づいて分岐できます。承認フローや複数ステップの意思決定ロジックを支える仕組みです。
• checkpointer(テストではインメモリ、本番ではSQLiteまたはPostgres)によって、グラフはセッションをまたいで再開でき、thread_idをキーにします。

次のステップ

LangGraphは、動作するagentへのコードによる道のひとつであり、唯一のものではありません。CrewAIでAIエージェントを構築するでは、マルチエージェント向けのより役割ベースのフレームワークを解説しています。また、コードを書くかビジュアルビルダーを使うかをまだ決めかねているなら、AIエージェントプラットフォームの選び方で、no-code、フレームワーク、マネージドの選択肢全体にわたるその判断を解説しています。グラフがテストで安定して動くようになったら、AIエージェントの本番デプロイで、実際の処理量に触れる前のロールアウトとロールバックの計画を解説しています。コードそのものをより速く書き、保守するための次の参考として、開発ツールのまとめとAIコーディングアシスタントの購入ガイドも役立ちます。