ecosystem-primer

LangChain Inc. は、エージェントを構築するための3層構成のオープンソースツールと、可観測性を提供する LangSmith を提供しています。スタックを上から順に示します。

• Deep Agents（最上位層、ハーネス） — LangChain と LangGraph を基盤とする、必要な機能が一通りそろったツールキットです。計画立案、ファイル管理、サブエージェントの起動、メモリを標準で備えています。
• LangGraph（中間層、ランタイム） — 耐久性のある実行、カスタム制御フロー、ステートフルなワークフローを実現する低レベルのオーケストレーションです。LangChain エージェントは LangGraph 上で動作します。
• LangChain（最下層、フレームワーク） — モデル、ツール、エージェントのループに関する抽象化を提供します。プロバイダーに依存せず、最も手軽に使い始められます。
• LangSmith（横断的な層） — 可観測性と評価のプラットフォームです。フレームワークに依存せず、上記のいずれと併用する場合にも推奨されます。

上位層は下位層に依存しますが、下位層を直接使う必要はありません。Deep Agents を使えば、グラフのコードを書かずに LangGraph の耐久性のある実行を利用できます。LangChain を使えば、グラフのエッジを管理せずにモデルとツールを利用できます。

---

ステップ 1 — ツールを選ぶ

以下の条件を順番に確認し、最初に一致した時点で判断を止めます。

1. 計画立案、長時間のセッションにわたるファイル管理、永続メモリ、サブエージェントへの委任、または必要に応じたスキルの利用が必要な場合 → Deep Agents
2. それ以外で、カスタム制御フロー（決定論的なループ、分岐ロジック）が必要な場合 → LangGraph
3. それ以外で、ツールのセットが固定された単一目的のエージェントの場合 → LangChain（create_agent 関数）
4. それ以外で、エージェントのループを伴わない純粋なモデル呼び出し、検索パイプライン、またはシンプルなプロンプトチェーンの場合 → LangChain（モデルの直接呼び出し／チェーン）

これが選択するレイヤーです。ただし、まだ完了ではありません。ステップ 4 では、エージェントのコードを書く前に、必ずレイヤー固有のスキルを読み込む必要があります。

---

ツールの概要

LangChain — エージェントフレームワーク

最適な用途：

• ツールのセットが固定された単一目的のエージェント
• RAG パイプラインとドキュメントに関する Q&A
• モデル呼び出し、プロンプトテンプレート、構造化出力

あまり適さない用途：

• エージェントが多くのステップにわたる計画立案や、大規模なコンテキストの管理を必要とする場合
• 制御フローが条件付き、反復的、または並列の場合
• 状態をセッション間で保持する必要がある場合

LangChain のエージェントはすべて create_agent(model, tools=[...]) を使用します。

LangGraph — エージェントランタイム

最適な用途：

• カスタム制御フロー — 決定論的なループ、リフレクションサイクル、並列のファンアウト
• 決定論的なステップとエージェント的なステップを組み合わせた複雑なワークフロー
• 中断と再開のポイントを厳密に設定するヒューマン・イン・ザ・ループ
• 障害を越えて保持する必要がある状態や、長時間のセッションにわたる状態

あまり適さない用途：

• 計画立案、ファイル管理、サブエージェントへの委任を標準で利用したい場合（代わりに Deep Agents を使用してください）
• ワークフローが単純で、通常のツールループで十分な場合

LangGraph のグラフはすべて StateGraph(State) を使用し、ノード、エッジ、条件付きエッジを明示的に定義します。

Deep Agents — エージェントハーネス

最適な用途：

• 計画立案とタスクの分解が必要な長時間実行タスク
• セッション中にファイルを読み取り、書き込み、管理するエージェント
• サブタスクを専門のサブエージェントに委任すること
• セッション間での永続メモリ
• ドメイン固有のスキルを必要に応じて読み込むこと

あまり適さない用途：

• タスクが単一目的のエージェントで十分なほど単純な場合
• グラフのすべてのエッジを厳密に手作業で制御する必要がある場合（代わりに LangGraph を直接使用してください）

Deep Agents はすべて create_deep_agent(model, tools=[...]) を使用します。

---

レイヤーの組み合わせ

各ツールはレイヤー化されているため、同じプロジェクト内で組み合わせて使用できます。よくあるパターンは次のとおりです。

• Deep Agents オーケストレーター → LangGraph サブエージェント — メインエージェントに計画立案とメモリが必要で、サブタスクの1つに決定論的なグラフが必要な場合。
• LangGraph グラフをツールまたはサブエージェントとしてラップする — 特化したパイプライン（例：RAG、リフレクションループ）を、より広範なエージェントから呼び出す場合。

コンパイル済みの LangGraph グラフは、Deep Agents 内で名前付きサブエージェントとして登録できます。オーケストレーターは内部構造を知らなくても、task ツールを介して処理を委譲できます。LangChain のツールとリトリーバーは、LangGraph のノード内と Deep Agents のツール内のどちらでも自由に使用できます。

---

ステップ 2 — 環境変数の設定

可観測性を確保するため、これらの環境変数は必ず設定してください。これらは現在の LangSmith 環境変数名です。そのままコピーしてください。古い名前はもう機能しません。

LANGSMITH_API_KEY= LANGSMITH_TRACING=true LANGSMITH_PROJECT=

モデルプロバイダーやツール固有のキー（ANTHROPIC_API_KEY、OPENAI_API_KEY、TAVILY_API_KEY など）は、スタックによって異なります。必要に応じて設定してください。

---

ステップ 3 — ドキュメントの利用方法

すべてのドキュメントは docs.langchain.com にあり、トップレベルの2つのセクションに分かれています。

• OSS — LangChain、LangGraph、Deep Agents。Python（/oss/python/）と TypeScript（/oss/javascript/）のツリーが並行して用意されています。
• LangSmith — 可観測性、評価、デプロイ、プロンプトエンジニアリング。

各製品には独自のページツリーがあります。概要 → クイックスタート → ハウツーガイド → リファレンスの順です。

基本のランディングページ

ルートからツリーを検索するのではなく、まずこちらを参照してください（TypeScript の場合は python を javascript に置き換えます）。

• LangChain — /oss/python/langchain/overview
• LangGraph — /oss/python/langgraph/overview
• Deep Agents — /oss/python/deepagents/overview
• LangSmith — /langsmith/home（言語による分岐はありません）

エージェントのコンテキストでドキュメントにアクセスする

LangChain Docs MCP サーバーが接続されている場合（mcp__docs-langchain__* ツールを利用できます）は、直接クエリしてください。

tree /oss/python -L 2                        # explore Python structure
tree /oss/javascript -L 2                    # parallel TypeScript structure
cat /oss/python/langchain/quickstart.mdx     # read a specific page
rg -il "checkpointer" /oss/python/langgraph/ # search by keyword

MCP サーバーを利用できない場合は、llms.txt インデックスを使用してください。

1. https://docs.langchain.com/llms.txt を取得します。全ページの説明付きリストが構造化されています。
2. 質問に最も関連するページを2～4件特定します。
3. 正確で最新の情報を得るため、それらのページを直接取得します。

トレーニングデータの知識に頼るより、常に最新のドキュメントを取得してください。これらのライブラリは急速に進化し、APIも頻繁に変更されます。

---

ステップ 4 — 次に適切なスキルを読み込む

ユーザーが最小限のローカルで動作するエージェント（新規プロジェクト、スタブツール、プロバイダーキー）のみを求めている場合は、まず対応するクイックスタートを読み込んでください。

• LangChain → langchain-python-quickstart または langchain-typescript-quickstart
• LangGraph → langgraph-python-quickstart または langgraph-typescript-quickstart
• Deep Agents → deepagents-python-quickstart または deepagents-typescript-quickstart

それ以外の場合は、ステップ 1 のレイヤーに対応する以下のスキルを読み込んでください。これは必須です。レイヤー固有のスキルには現在の API が含まれており、入門資料だけでは不十分です。

LangChain

• langchain-fundamentals — LangChain エージェントの構築全般
• langchain-rag — RAG／ベクトルストア検索の追加
• langchain-middleware — Pydantic による構造化出力
• langchain-dependencies — パッケージのバージョン、インストール、依存関係の管理に関する質問

LangGraph

• langgraph-fundamentals — LangGraph グラフ全般
• langgraph-human-in-the-loop — 人間参加型の処理または承認ワークフロー
• langgraph-persistence — 再起動後も保持する必要がある状態、またはスレッド間で共有するメモリ

Deep Agents

必ず最初に deep-agents-core を読み込んでください。 その後、必要に応じて以下を読み込みます。

• deep-agents-orchestration — サブエージェントへの委譲またはオーケストレーション
• deep-agents-memory — セッションをまたいで保持されるメモリ