ほとんどのエージェントコードは最初はシンプルですが、そのリトライ処理のせいで破綻してしまいます。LLMを接続し、いくつかのツールを与えたとたん、ワークフローがループ、分岐、または人間による一時停止を必要とすると、一直線のスクリプトは崩壊します。LangGraphはまさにその混乱のために作られたフレームワークです。共有状態を持つグラフとしてエージェントをモデル化するため、ループと分岐が絡み合ったif文ではなく、第一級の構造となります。このガイドでは、LangGraphとは何か、それが解決する問題、そしてエージェントが実際のサービスを呼び出す際にAPIテストがどのように役立つかを説明します。
LangGraphとは
LangGraphは、長時間実行されるステートフルなエージェントを構築するための低レベルなオーケストレーションフレームワークおよびランタイムです。LangChainのチームであるLangChain Incによって構築されましたが、独自の焦点を持つ別のライブラリです。pip install -U langgraphで単独でインストールでき、LangChainエコシステムの他の部分なしで使用できます。
その核となるアイデアはシンプルです。エージェントをグラフとして記述します。ノードは作業（モデルの呼び出し、ツールの実行、データの変換）を行い、エッジは次に何を実行するかを決定します。共有状態オブジェクトはすべてのノードを流れ、各ノードはそれを読み書きできます。エッジが後方を指すことができるため、グラフはサイクルを形成できます。これは、通常のチェーンではうまくできない部分です。
LangChainの古いChain抽象化を使用したことがあるなら、違いは制御フローの形にあります。チェーンはパイプラインです。ステップ1、ステップ2、ステップ3、完了。グラフでは、ノードが現在の状態を検査し、別のブランチにジャンプしたり、リトライのためにループバックしたり、複数のノードに分岐して並行して実行し、その結果をマージしたりできます。実際のAIエージェントにはこれが必要です。「推論し、行動し、観察し、再び推論する」というのはループであり、直線ではないからです。
LangGraphが解決する問題
エージェントワークフローは本質的に循環的です。エージェントはツールを呼び出し、結果を見て、完了したかどうかを判断し、完了していなければ再度試行します。これをネストされた条件文でモデル化するとすぐに読みにくくなり、本番エージェントが実際に必要とするものを追加するとさらに悪化します。
- 停止条件付きループ。 タスクが完了するまでツールを呼び出し続け、無限ループに陥らないようにします。
- 状態に応じた分岐。 モデルが返した内容に応じて別のノードにルーティングします。
- 永続性。 クラッシュ、タイムアウト、再起動から回復し、最後の正常なポイントから再開します。
- ヒューマン・イン・ザ・ループ。 一時停止し、人が状態を検査または編集できるようにしてから続行します。
- ストリーミング。 トークンと中間ステップを発生と同時に出力し、最後だけではありません。
LangGraphは、これらのそれぞれを手動で作成するのではなく、組み込みの機能に変えます。永続的な実行が可能なステートマシンが得られるため、エージェントは数分または数時間実行し、停止した場所から再開できます。
主要な概念：グラフ、状態、ノード、エッジ
4つのプリミティブがフレームワークのほとんどを支えています。それらがどのように連携するかを説明します。
状態 (State) は、実行全体で共有される型付きオブジェクトです。スキーマ（多くの場合TypedDict）でその形状を定義し、LangGraphは各ノードの更新をそれにマージします。一般的な出発点として、チャットメッセージの実行リストを保持する組み込みスキーマであるMessagesStateがあります。
ノード (Nodes) は関数です。それぞれが現在の状態を受け取り、部分的な更新を返します。これらはadd_node()で登録します。
エッジ (Edges) はノードを接続します。add_edge()による通常の接続は常にAからBへ進みます。add_conditional_edges()による条件付きエッジは、状態を読み取って次のノードの名前を返すルーティング関数を実行します。これは、「モデルがツールを要求した場合はそれを実行し、そうでなければ終了する」という条件を表現する方法です。
STARTとENDは、実行の開始と停止を示す特殊なマーカーです。
最小限のグラフの形状を以下に示します。これは疑似コードレベルですが、API名は実際のものです。
from langgraph.graph import StateGraph, START, END, MessagesState
def call_model(state: MessagesState):
response = model.invoke(state["messages"])
return {"messages": [response]}
def should_continue(state: MessagesState) -> str:
last = state["messages"][-1]
return "tools" if last.tool_calls else END
builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", tool_node)
builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model") # loop back
graph = builder.compile()
add_edge("tools", "model")の行がサイクルです。ツールが実行された後、制御はモデルに戻り、モデルはさらにツールを呼び出すか停止できます。このループこそがLangGraphが存在する理由の全てです。
永続性とヒューマン・イン・ザ・ループ
チェックポインターを使用してグラフをコンパイルすると、各ステップの後に状態のスナップショットが保存されます。configでthread_idを渡すと、LangGraphはそのスレッドの最新のチェックポイントを次回の呼び出し時に復元します。ノードは変更されず、ランタイムが保存と復元を処理します。
from langgraph.checkpoint.memory import InMemorySaver
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [user_message]}, config)
InMemorySaverは開発用には十分です。再起動後も状態を維持するには、LangGraphにはデータベースをバックエンドとするセーバー（単一サーバー用SQLite、マルチインスタンス規模用Postgres）が同梱されています。状態は永続的であるため、ヒューマン・イン・ザ・ループもほぼ無料で実現できます。グラフを任意のポイントで中断し、現在の状態を人が検査または編集できるように提示し、その正確なチェックポイントから再開できます。承認ゲート、手動修正、「本当によろしいですか？」といったステップはすべてこれを基盤として構築されます。
ストリーミングがそれを完成させます。LangGraphは、実行が進むにつれてモデルのトークンやノードレベルの更新をストリーミングできるため、UIはスピナーを凝視する代わりにエージェントが考えている様子を表示できます。
LangGraphとLangChainの関係
これは人々を混乱させるので、直接的に説明しましょう。LangChainはより広範なツールキットであり、モデルラッパー、プロンプトテンプレート、リトリーバー、ドキュメントローダー、そして数百のプロバイダーとの統合を含みます。LangGraphは、そのツールキットのエージェント部分を支えるオーケストレーション層です。
LangGraphを使用するためにLangChainは必要ありません。独自のステート、ノード、エッジを定義し、ノード内で好きなモデルクライアントを呼び出すことができます。多くのチームはこれら2つを組み合わせて使用します。LangChainのモデルとツールの抽象化が便利であること、そしてLangGraphの組み込みcreate_react_agentヘルパー（langgraph.prebuilt内）が、カスタムグラフを必要としない場合に、数行で動作するツール呼び出しエージェントを提供するためです。
| LangChain | LangGraph | |
|---|---|---|
| 役割 | コンポーネントと統合 | オーケストレーションとランタイム |
| 制御フロー | 線形チェーン | サイクルと分岐を持つグラフ |
| 組み込み状態 | 限定的 | 共有、型付き、永続的 |
| 永続性 / 再開 | 主要な焦点ではない | チェックポインター + スレッドID |
| 最適用途 | モデル呼び出しとツールの構成 | ステートフルな多段階エージェント |
現在のユーザーへの注意点：LangGraph v1.0系列（2025年後半から安定版）では、組み込みのエージェントヘルパーがlangchain.agents.create_agentへと移行しているため、古いスニペットをコピーする前に、インストールされているバージョンと正確なインポートパスについて公式リファレンスを確認してください。ゼロからカスタムエージェントを構築することもここで役立つスキルです。より広範な内容については、カスタムAIエージェントの構築に関するチュートリアルを参照してください。
LangGraph PlatformとStudio
オープンソースライブラリが核ですが、デプロイ後に重要になる2つの関連製品があります。
LangGraph StudioはビジュアルなエージェントIDEです。グラフをレンダリングし、実行させ、各ノードでの状態を表示するため、ノードとエッジを介して実行がどのように進行するかを確認できます。サイクルや条件付きルーティングがあるものについては、エージェントが実際にたどったパスを見ることはログ行を読むよりも優れています。
LangGraph Platformは、管理されたデプロイメント側です。エージェント用のAPIエンドポイント、長時間実行される処理のための組み込み永続性、そしてセルフホストからクラウドでのフルマネージドまで幅広いホスティングオプションを提供します。ライブラリを使用するためにこれが必要なわけではありません。エージェントを自分で実行するのではなく、本番環境でエージェント用のインフラが必要な場合に利用できます。
LangGraphを使用すべき時
エージェントに真の制御フローがある場合、LangGraphに手を伸ばしてください。良い兆候は次のとおりです。
- 作業がシーケンスではなくループである場合（ツールを呼び出し、確認し、繰り返す）。
- モデルが決定した内容に基づいて分岐する必要がある場合。
- 実行が長時間にわたる可能性があり、クラッシュから復旧して再開したい場合。
- 実行中に人間が何かを承認または編集する必要がある場合。
- 状態を共有する複数のアクターまたはサブエージェントを調整している場合。
単一のモデル呼び出しや短い線形チェーンで事足りる場合は、使用をスキップしてください。「このテキストを要約する」といった単純なタスクにグラフは不要なオーバーヘッドです。真に分岐し、ループするワークフローのために構造を温存してください。
APIテストとモックがどのように適合するか
ここが開発チームを悩ませる部分です。LangGraphエージェントは、それが呼び出すAPIと同じくらい信頼性が高く、そのAPIの数は多岐にわたります。LLMエンドポイントに加え、あらゆるツールAPI（検索、CRM、独自のバックエンドなど）です。LangGraphはこれらの呼び出しをオーケストレーションしますが、テストはしません。それは別の仕事であり、そこでApidogが登場します。
すぐに2つの問題が現れます。第一に、すべてのテスト実行でライブAPIにアクセスすると、トークンを消費し、レート制限に引っかかります。APIをモックすることで、グラフロジックを反復処理している間、ツールエンドポイントが確定的で即時の応答を返すようにできます。LLMエンドポイントも同様にモックすれば、ルーティングをテストするためだけにトークン料金を支払う必要がなくなります。
第二に、ノードは応答の形状を想定しています。もしツールのAPIがひそかにフィールド名を変更した場合、条件付きエッジが間違ったものを読み取り、エージェントはループしたり停止したりします。APIアサーションでこれらの契約を固定することで、変更がグラフに到達する前に検出できます。また、エージェントはステージング環境と本番環境でキーをやりくりするため、それらを環境で管理することで、シークレットがノードコードから漏れるのを防ぎます。エージェントに特化した完全なワークフローが必要な場合は、AIエージェント用のApidogテストハーネスがその全容を説明しています。明確にしておきますが、これらはエージェントをオーケストレーションするものではありません。Apidogはエージェントの下にあるAPIをテストし、モックするものです。
よくある質問
LangGraphはLangChainの代替ですか？ いいえ。LangGraphはオーケストレーションランタイムであり、LangChainはより広範なコンポーネントと統合のセットです。これらは同じチームが開発した別々のライブラリであり、LangChainなしでLangGraphを実行することも、両方を一緒に使用することもできます。LangGraphは、通常のチェーンが苦労するステートフルで循環的な制御フローを処理します。
LangGraphを始めるためにLangChainを知っている必要がありますか？ いいえ。StateGraphを定義し、ノードとエッジを追加し、ノード内で好きなモデルクライアントを呼び出すことができます。LangChainのモデルラッパーは便利ですが、必須ではありません。まずコアのグラフプリミティブから始め、必要な場合にのみ残りの機能を追加してください。
LangGraphは呼び出し間でどのように情報を記憶していますか？ チェックポインターを介して記憶します。チェックポインターを使ってグラフをコンパイルし、thread_idを渡すと、LangGraphは各ステップの後に状態スナップショットを保存し、そのスレッドの次回の呼び出し時にそれを復元します。これにより、ノードロジックを変更することなく、会話の記憶とクラッシュからの回復を実現できます。
エージェントが呼び出すAPIをどのようにテストしますか？ グラフとは別にテストし、モックしてください。LLMとツールエンドポイントをモックすることで、開発中の実行を高速かつ無料にし、応答の形状をアサートすることで、フィールド変更がノードを破損しないようにします。ChatGPT APIのテストに関するガイドでは、認証、ストリーミング、ツール呼び出しなど、エージェントが依存する正確なインターフェースについて説明しています。
まとめ
LangGraphは、ループし、分岐し、永続化し、人間の介入のために一時停止するエージェントに必要な構造を提供します。ワークフローを共有状態を持つグラフとしてモデル化し、メモリと回復のためにチェックポインターに頼り、デバッグとデプロイの準備ができたらStudioとPlatformを使用します。フレームワークはオーケストレーションを処理します。エージェントが呼び出すAPIにはまだ独自の安全ネットが必要ですので、開発コストを抑え、ツールの契約を確実に守るために、Apidogでそれらをモックしてテストしてください。エージェントが実際にエンドポイントにアクセスする前に、それをモックし、応答をアサートするためにApidogをダウンロードしてください。