langgraph-fundamentals について
LangGraph のワークフローを設計、実装、デバッグするためのガイドです。分岐やループ、ストリーミング、永続化を伴うステートフルなエージェント制御を扱います。
主な機能
- 01StateGraph の設計とコンパイル
- 02状態とリデューサーの指針
- 03静的・条件付きルーティング
- 04Command と Send のパターン
- 05呼び出しとストリーミング方式
- 06エラー処理の方針
活用シーン
- 01分岐するエージェントワークフローの設計
- 02蓄積されるグラフ状態の管理
- 03UI へのグラフ進行状況の配信
- 04一時的・ユーザー修正可能なエラーへの対応
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/langgraph-fundamentalsを入力して読み込まれたか確認します。
同梱ファイルreferences/python.mdreferences/typescript.md
詳細
- StateGraph：ステートフルなグラフを構築するメインクラス
- ノード：処理を実行し、状態を更新する関数
- エッジ：実行順序を定義します（静的または条件付き）
- START/END：開始点と終了点を示す特別なノード
- Reducer を使った状態：状態の更新をどのように統合するかを制御します
グラフは実行前に compile() する必要があります。
LangGraph アプリケーションの設計
新しいグラフを構築するときは、次の 5 つのステップに従ってください。
- 個別のステップを洗い出す — ワークフローのフローチャートを描きます。各ステップが 1 つのノードになります。
- 各ステップの処理内容を特定する — ノードを LLM ステップ、データステップ、アクションステップ、ユーザー入力ステップに分類します。それぞれについて、静的コンテキスト（プロンプト）、動的コンテキスト（状態から取得）、リトライ戦略、期待する結果を決めます。
- 状態を設計する — 状態はすべてのノードで共有されるメモリです。生データを保存し、ノード内で必要に応じてプロンプトを整形します。
- ノードを構築する — 各ステップを、状態を受け取り部分的な更新を返す関数として実装します。
- 全体を接続する — エッジでノードを接続し、条件付きルーティングを追加します。必要に応じてチェックポインターを指定してコンパイルします。
| LangGraph を使う場合 | 代替手段を使う場合 |
|---|---|
| エージェントのオーケストレーションをきめ細かく制御する必要がある | 手早くプロトタイプを作成する → LangChain エージェント |
| 分岐やループを含む複雑なワークフローを構築する | シンプルなステートレスワークフロー → LangChain direct |
| Human-in-the-loop や永続化が必要である | すぐに使える機能が必要である → Deep Agents |
状態管理
| 必要な処理 | 解決策 | 例 |
|---|---|---|
| 値を上書きする | Reducer なし（デフォルト） | カウンターなどの単純なフィールド |
| リストに追加する | Reducer（operator.add / concat） | メッセージ履歴、ログ |
| カスタムロジックを使う | カスタム Reducer 関数 | 複雑な統合 |
ノード
ノード関数は、状態の部分的な更新を返します。設定と実行時アクセスのシグネチャは言語によって異なるため、該当する実装リファレンスを参照してください。
エッジ
| 必要な処理 | エッジの種類 | 使用する場面 |
|---|---|---|
| 常に同じノードに進む | add_edge() | 固定された決定論的なフロー |
| 状態に基づいてルーティングする | add_conditional_edges() | 動的な分岐 |
| 状態を更新し、ルーティングする | Command | 1 つのノードにロジックをまとめる |
| 複数のノードにファンアウトする | Send | 動的な入力による並列処理 |
Command
Command は、状態の更新とルーティングを 1 つの戻り値にまとめます。フィールドは次のとおりです。
update：適用する状態の更新（ノードから dict を返す場合と同様）goto：次に進むノード名resume：interrupt()の後に再開する値 — human-in-the-loop スキルを参照してください
Python：有効な goto 先を宣言する戻り値の型アノテーションとして、Command[Literal["node_a", "node_b"]] を使います。
TypeScript：有効な goto 先を宣言するには、addNode の第 3 引数に { ends: ["node_a", "node_b"] } を渡します。
警告：Command が追加するのは動的エッジのみです。add_edge / addEdge で定義した静的エッジも引き続き実行されます。node_a が Command(goto="node_c") を返し、さらに graph.add_edge("node_a", "node_b") も設定されている場合、node_b と node_c の両方が実行されます。
Send API
Send によるファンアウト：条件付きエッジから [Send("worker", {...})] を返すと、並列ワーカーを起動できます。結果フィールドには Reducer が必要です。
グラフの実行：呼び出しとストリーミング
graph.invoke(input, config) を呼び出すと、グラフを最後まで実行し、最終状態を返します。
| モード | ストリーミングされる内容 | 用途 |
|---|---|---|
values | 各ステップ後の全状態 | 完全な状態の監視 |
updates | 状態の差分 | 段階的な更新の追跡 |
messages | LLM のトークンとメタデータ | チャット UI |
custom | ユーザー定義データ | 進捗インジケーター |
エラー処理
エラーの種類に応じて、適切なハンドラーを選択します。
| エラーの種類 | 修正する担当 | 対処方法 | 例 |
|---|---|---|---|
| 一時的なエラー（ネットワーク、レート制限） | システム | RetryPolicy(max_attempts=3) | add_node(..., retry_policy=...) |
| LLM で回復可能（ツールの失敗） | LLM | ToolNode(tools, handle_tool_errors=True) | ToolMessage として返されるエラー |
| ユーザーが修正可能（情報不足） | 人間 | interrupt({"message": ...}) | 不足しているデータを収集（HITL スキルを参照） |
| 想定外 | 開発者 | エラーを上位に伝播させる | raise |
主な境界
- 状態を直接変更するのではなく、ノードから部分的な状態更新を返します。
- ループは名前付きノードを経由させます。
STARTはエントリ専用です。 - 累積するリストフィールドにはリデューサーを定義します。定義しない場合、最後の書き込みが優先されます。
gotoを指定したCommandを使用する場合は、静的エッジも考慮してください。両方の経路が実行されます。
実装リファレンス
LangGraph コードを作成、変更、またはデバッグする場合は、既存のファイルからプロジェクトの言語を確認し、実装前に該当するリファレンスを読んでください。
- Python の場合は、references/python.md を読んでください。
- TypeScript の場合は、references/typescript.md を読んでください。
タスクが両方の言語に関わる場合にのみ、両方を読んでください。コードを必要としない概念的な質問では、どちらのリファレンスも読み込まないでください。