langgraph

LangGraph

LangGraph は LangChain の低レベルなオーケストレーションフレームワークです。Pregel／Beam と NetworkX に着想を得た有向グラフアーキテクチャを使い、状態を持つ長時間実行型のマルチエージェント AI ワークフローを構築できます。エージェントをグラフ内のノードとしてモデル化し、エッジでフローを制御することで、循環、条件分岐、並列実行、ヒューマン・イン・ザ・ループ、サブグラフの合成を実現できます。これらは線形チェーンでは表現できません。

このスキルでは、LangGraph システムの構築とデプロイに関する主要なパターンを網羅します。コアとなるグラフアーキテクチャ、代表的な 3 つのマルチエージェントパターン（スーパーバイザー、スウォーム、階層型）、永続化と状態管理、本番環境でのデバッグ、評価手法を扱います。

始める前に： 依存関係をインストールします。

pip install langgraph langchain langchain-openai langsmith

クイックスタート

10 行以内で最初の LangGraph エージェントを作成します。

from langgraph.graph import StateGraph, MessagesState, START, END

def hello_agent(state: MessagesState):
    return {"messages": [{"role": "ai", "content": "Hello, world!"}]}

graph = StateGraph(MessagesState)
graph.add_node("agent", hello_agent)
graph.add_edge(START, "agent")
graph.add_edge("agent", END)
graph = graph.compile()

graph.invoke({"messages": [{"role": "user", "content": "hi!"}]})

次のステップ：

1. 以下のパターン選択ガイドを使って、スーパーバイザー、スウォーム、階層型のアーキテクチャを選びます。各パターンには、推奨テンプレートへのリンクがあります
2. 該当するリファレンスファイルを読み込み、パターンの詳細な解説を確認します
3. 以下の開始地点の選び方の表を使い、タスクに応じてスキャフォールド、テンプレート、リファレンスを選びます
4. 選んだパターンに合った実行可能な完全な例を確認するには、assets/templates/ 内のリンク先テンプレートを使います

設計原則 — あらゆるグラフ設計の判断に適用されます

1. 状態が信頼できる唯一の情報源です — ノード間の通信はすべて、サイドチャネルやグローバル変数ではなく状態を通じて行います。
2. ノードはほぼ純粋です — ノードは状態を受け取り、処理を行い、更新内容を返します。渡されていない状態に依存してはいけません。
3. リデューサーで競合を防ぎます — 並列実行される複数のノードが書き込む状態キーには、必ずリデューサーを指定します。
4. シンプルに始めます — 適切なプロンプトを備えた単一エージェントは、ルーティングが適切でないマルチエージェントシステムより優れています。単一のプロンプトやツールセットで扱いきれなくなった場合にのみ、エージェントを追加します。
5. 動的なファンアウトには Send() を使います — コンパイル時に必要なワーカー数が分からない場合は、オーケストレーターノードから動的にワーカーを生成します。
6. サブグラフの状態を分離します — 状態スキーマが異なるサブグラフには、境界で状態を変換するラッパー関数が必要です。共有スキーマのサブグラフは、ノードとして直接追加できます。

どの場面で使うか

コンテキスト	読み込むもの
LangGraph ワークフローをゼロから構築する	references/architecture.md — まずコア概念を確認
マルチエージェントのルーティングシステムを設計する	references/multi-agent-supervisor.md または references/multi-agent-swarm.md — パターンを比較
入れ子になったエージェントチームを構成する	references/multi-agent-hierarchical.md — サブグラフの合成
永続化、中断、長期記憶を追加する	references/persistence.md — チェックポインターとストア
本番環境にデプロイする、または障害をデバッグする	references/production.md — デプロイ、可観測性、障害モード
ルーティング精度を評価するパイプラインを設定する	references/evals.md — 評価手法
特定の障害（ループ、コンテキストの喪失、クラッシュ）を診断する	references/troubleshooting.md — 既知の障害モード
型付き System One 判断をグラフに配置する	references/architecture.md。判断の契約とキャリブレーションについては System One、ワークフローの権限とタスク全体のエビデンスについては harness-engineering を参照

パターン選択ガイド

制約	推奨	理由
レイテンシよりルーティング精度を優先	Supervisor	集中型のルーティングノードと特化したプロンプトにより、精度は約94％です
レイテンシが最優先の制約	Swarm	エージェント間で直接ハンドオフするため、LLM 呼び出しが約40％減少します
ドメインの境界が明確	Swarm	エージェントが誤ったルーティングをすることはまれで、ハンドオフも明確です
ドメインの境界が曖昧	Supervisor	重複する懸念事項を専用ルーターで解決できます
個別のドメインが3つ未満	マルチエージェントを使わない	特化した単一エージェントのほうがシンプルです
複数ドメインにまたがるリクエストが多い	Swarm	ハンドオフを重ねるほどレイテンシ削減の効果が高まります
集中管理された監査証跡が必要	Supervisor	すべてのルーティング判断をトレースで確認できます
入れ子になったチーム構造	Hierarchical	サブグラフをノードとして使い、各チームを独立させます

開始地点の選び方

目標	開始地点	理由
プロジェクトをゼロから構築し、コードを生成したい	scripts/lg-supervisor-scaffold.py または scripts/lg-swarm-scaffold.py	スキャフォールドは、記入するプレースホルダーを含む完全なプロジェクト構造（state.py、agents.py、graph.py）を生成します
完全に動作するサンプルを理解したい	選択したパターンに対応する assets/templates/	テンプレートは、すべてのパターンが組み込まれた自己完結型の実行可能ファイルです。コードを読んで学ぶのに最適です
パターンの内部を詳しく知りたい	references/ 内の対応するリファレンス	リファレンスではトレードオフ、障害モード、設計の根拠を説明しています。カスタマイズに最適です
既存システムをデバッグまたは最適化したい	references/production.md または references/troubleshooting.md	本番環境リファレンスではデプロイと可観測性を、トラブルシューティングリファレンスでは症状から対処法を示す表を扱います

コアプリミティブ

LangGraph には2つの API があります。

API	使用する場面	パターン
Graph API (StateGraph)	グラフ構造、条件付きエッジ、サブグラフを完全に制御する場合	add_node() + add_edge()/add_conditional_edges()
Functional API (@task + @entrypoint)	よりシンプルな線形ワークフローで、定型コードを減らしたい場合	デコレーターを使った、Python らしい書き方

どちらの API も同じコンパイル済みグラフを生成します。必要な制御の度合いに応じて選択してください。

主な注意点

• サブグラフの永続化はデフォルトで呼び出しごとです — 各サブグラフの呼び出しは新しい状態から始まります。スレッド単位のメモリには checkpointer=True を、完全なステートレス動作には checkpointer=False を設定します。
• スレッド単位のサブグラフは並列実行できません — 同じ名前空間のチェックポイントが競合します。ToolCallLimitMiddleware を使うか、ツール呼び出しの並列実行を無効にしてください。
• Supervisor のボトルネック — 明白なインテントであっても、すべてのやり取りでルーティング用の LLM 呼び出しが必要です。曖昧さのないリクエストには、高速な分類器（キーワード照合や小規模モデル）を追加してください。
• Swarm のピンポン — 自然な再帰ガードがありません。状態で handoff_count を追跡し、3回を上限として、その後は人間またはフォールバックエージェントにエスカレーションしてください。
• ハンドオフ時のメッセージ喪失 — Command.update には、スペシャリストのツール呼び出しループから対応するメッセージ一式を含める必要があります。そうしないと、次のエージェントが不正な履歴を受け取ります。
• 親からサブグラフへの状態アクセス — サブグラフは独自のチェックポイント名前空間を管理します。グラフ境界をまたぐデータには Store を使ってください。
• チェックポイントの肥大化 — 長い会話ではチェックポイントが蓄積します。定期的に削除するか、DB ベースのチェックポインターに保持ポリシーを設定してください。
• インストール時に自動読み込みされません — セッション開始時に、名前への言及によってスキルが自動検出されることはありません。このスキルを読み込むには、エージェントが明示的に skill_view(name='langgraph') を呼び出す必要があります。

参考ファイル

ファイル	読み込むタイミング
references/architecture.md	LangGraph の中核となる概念（グラフ構造、ノード、エッジ、状態、2 つの API、基本的なエージェントループの構築）を理解する必要がある場合に読み込みます。LangGraph を初めて使う場合は、まずこれを読んでください。
references/multi-agent-supervisor.md	中央のルーティングノードを使用するスーパーバイザーベースのマルチエージェントシステムを設計する場合に読み込みます。アーキテクチャ、構造化出力によるルーティング、スペシャリストのラッパー、コードの完全な例を含みます。
references/multi-agent-swarm.md	エージェント間で直接ハンドオフするスウォームベースのマルチエージェントシステムを設計する場合に読み込みます。ハンドオフツールのパターン、Command ベースのルーティング、スーパーバイザーとの比較指標を含みます。
references/multi-agent-hierarchical.md	サブグラフを使用して、入れ子構造のエージェントチームを構成する場合に読み込みます。サブグラフの接続（共通または異なる状態スキーマ）、永続化モード、名前空間の分離、階層型チーム構造について説明します。
references/persistence.md	チェックポインターによる短期メモリまたはストアによる長期メモリを追加する場合に読み込みます。呼び出しごと、スレッドごと、ステートレスの各モード、チェックポイントのバックエンド、スレッドをまたぐメモリパターンを含みます。
references/production.md	LangGraph システムを本番環境にデプロイする場合に読み込みます。Agent Server のデプロイ、LangSmith の可観測性、ストリーミングのパターン、一般的な本番環境での障害とその修正方法を含みます。
references/evals.md	マルチエージェントシステムの評価パイプラインを設定する場合に読み込みます。ルーティングの精度、解決範囲、LangSmith の評価データセット、LLM-as-judge 評価器について説明します。
references/troubleshooting.md	LangGraph の特定の問題をデバッグする場合に読み込みます。ルーティングループ、コンテキストの喪失、チェックポインターの競合、トークンの浪費、状態の検査手法を含みます。
assets/templates/supervisor-graph.py	請求、テクニカルサポート、アカウントの各スペシャリストを備えた、実行可能なスーパーバイザーの例です。ファストパス分類器、構造化出力によるルーティング、監査証跡、再帰ガードを含みます。
assets/templates/swarm-graph.py	トリアージエージェントと 3 つのスペシャリストを備えた、実行可能なスウォームの例です。Command によるエージェント間の直接ハンドオフ、再帰ガード、完全なトレーサビリティを含みます。
assets/templates/subgraph-agent.py	実行可能なサブグラフ構成の例です。3 つの接続パターン（異なる状態スキーマ、共通の状態キー、名前空間の分離を伴うスレッドごとの構成）すべてを含みます。

スクリプト

スクリプト	機能
scripts/lg-supervisor-scaffold.py	状態スキーマ、ルーティングエージェント、スペシャリストノード、グラフの組み立てを含む、完全なスーパーバイザーパターンのプロジェクトを生成します。
scripts/lg-swarm-scaffold.py	ハンドオフツール、トリアージエージェント、スペシャリストエージェント、条件付きルーティングを含む、完全なスウォームパターンのプロジェクトを生成します。
scripts/lg-eval-generator.py	評価データセットを生成し、ルーティングの精度と解決範囲を評価する LangSmith 評価器を実行します。