langchain-oss-primer

**必ず最初にこのスキルを読み込んでください。** これは、他のスキルを選ぶ前、コードを書く前、パッケージをインストールする前に、LangChain のオープンソースエージェントプロジェクトで必ず最初に行う手順です。

すべてのプロジェクトで事前に解決すべき、次の3つの問いに答えます。

1. どのフレームワークを使うか？ — LangChain、LangGraph、Deep Agents
2. どのエージェントのアーキタイプを使うか？ — ユースケースに適した API とパターンを選びます
3. 何をインストールし、次にどのスキルを読み込むか？

まずこのスキルを読み込んでください。フレームワークとエージェントの種類を決めたら、最後にある「次のスキル」セクションに従ってください。選択に応じて次に呼び出すスキルが具体的に示されています。

---

ステップ 1 — フレームワークを選ぶ

3つのフレームワークは競合するものではなく、階層化されています。それぞれが下位のフレームワークを基盤としています。

┌─────────────────────────────────────────┐
│              Deep Agents                │  ← batteries included
│   (planning, memory, skills, files)     │
├─────────────────────────────────────────┤
│               LangGraph                 │  ← custom orchestration
│    (nodes, edges, state, persistence)   │
├─────────────────────────────────────────┤
│               LangChain                 │  ← foundation
│      (models, tools, prompts, RAG)      │
└─────────────────────────────────────────┘

次の質問に順番に答えてください。

質問	はい →	いいえ →
ユーザーが、計画立案、永続メモリ、複雑なタスク管理、長時間実行されるタスク、すぐに使えるファイル管理、オンデマンドのスキル、または組み込みのミドルウェア、サブエージェント、簡単な拡張機能を必要とする、または望んでいますか？	Deep Agents	↓
指定されたループ、分岐、決定論的な並列ワーカー、または手動で計測するヒューマン・イン・ザ・ループなど、カスタムの制御フローが必要ですか？	LangGraph	↓
固定されたツールセットを使う単一目的のエージェントですか？	LangChain（create_agent）	↓
エージェントループのない、シンプルなプロンプトパイプラインまたは検索チェーンですか？	LangChain（モデル／チェーンを直接使用）	—

上位の階層が下位の階層に依存するのは必要な場合のみです。組み合わせて使用できます。LangGraph のグラフは Deep Agents 内のサブエージェントにでき、LangChain のツールはどちらでも動作します。

	LangChain	LangGraph	Deep Agents
制御フロー	固定（ツールループ）	カスタム（グラフ）	管理（ミドルウェア）
ミドルウェア	コールバックのみ	✗ なし	✓ 明示的に設定可能
計画立案	✗	手動	✓ TodoListMiddleware
ファイル管理	✗	手動	✓ FilesystemMiddleware
永続メモリ	✗	チェックポインターを使用	✓ MemoryMiddleware
サブエージェントへの委任	✗	手動	✓ SubAgentMiddleware
オンデマンドのスキル	✗	✗	✓ SkillsMiddleware
ヒューマン・イン・ザ・ループ	✗	手動で中断	✓ HumanInTheLoopMiddleware
カスタムのグラフエッジ	✗	✓ 完全に制御可能	制限あり
セットアップの複雑さ	低	中	低

ミドルウェアは Deep Agents 固有の概念です（明示的なミドルウェア層）。LangGraph にミドルウェアはありません。動作はノードとエッジに直接組み込まれます。組み込みのフックや自動ミドルウェアをユーザーが求めている場合は、Deep Agents を選んでください。

---

ステップ 2 — エージェントのアーキタイプを選ぶ

フレームワークを選んだら、ユースケースに適した API とパターンを選びます。

LangChain — create_agent() を使用

固定されたツールセットを使う ReACT スタイルの単一目的エージェントに最適です。組み込みの計画立案、メモリ管理、委任機能はありません。

アーキタイプ	説明	主なツール
QA／チャットボット	質問への回答、要約、分類を行います。1つの仕事を確実にこなします。	LLM + 任意の検索機能
SQL エージェント	データベースをクエリし、構造化された結果を返します	SQLDatabase、create_agent
検索エージェント	情報を検索し、調査結果を返します	TavilySearchResults、DuckDuckGoSearch
RAG エージェント	ベクトルストアから取得し、文書に基づいて回答します	リトリーバーツール + create_agent
データ分析エージェント	構造化データを読み込み、変換し、要約します	PythonREPL、pandas ツール
ツール呼び出しエージェント	API の呼び出し、コードの実行、または任意のツールの連結を行います	カスタムの @tool 関数

すべての LangChain エージェントは create_agent(model, tools=[...]) を使用します。次のスキル：langchain-fundamentals。

### LangGraph — `StateGraph`を使用する

明示的で決定論的な制御フローが必要な場合に最適です。

アーキタイプ	説明	主なパターン
決定論的な並列ワークフロー	複数のノードに処理を分岐し、結果を収集してマージします	並列エッジ → 集約ノード
多段階パイプライン	型付き状態を使用した抽出 → 変換 → 読み込み	TypedDict状態 + 順次実行するノード
分岐型分類器	入力内容に基づいて、異なるハンドラーに振り分けます	条件付きエッジ + 分類ノード
リフレクションループ	明示的な終了条件を備えた、生成 → 批評 → 改訂のサイクル	サイクルエッジ + 反復カウンター
カスタムHITL	構造化されたレビューと条件付きエッジを使用する、複雑な人間参加型の処理	interrupt_before/interrupt_after + Commandによる再開

LangGraphのエージェントでは、明示的なadd_node、add_edge、add_conditional_edgesを使用してStateGraph(State)を構築します。次のスキル：langgraph-fundamentals。

Deep Agents — create_deep_agent()を使用する

タスクの計画、セッションをまたいだユーザーの記憶、専門家への委任、ファイルの自律的な管理など、エージェント自身が作業を管理する必要がある場合に最適です。

アーキタイプ	説明	Deep Agentsを使う理由
リサーチアシスタント	自由形式のリサーチ依頼を受け取り、サブタスクに分割して専門のサブエージェントに委任し、調査結果をまとめます	委任にはSubAgentMiddleware、計画にはTodoListMiddlewareが必要です
パーソナルアシスタント	複数のセッションをまたいで、ユーザーの好み、進行中のプロジェクト、コンテキストを記憶します	セッションをまたいだ永続化にはMemoryMiddleware（Store）が必要です
コーディングアシスタント	コードベースを読み取り、ファイルを書き込み、複数のステップにわたるリファクタリングを計画し、必要に応じて書き込み前に承認を求めます	FilesystemMiddleware + TodoListMiddleware + オプションのHITLが必要です
オーケストレーター	作業を2つ以上の専門サブエージェント（リサーチャー、コーダー、ライターなど）に振り分けるトップレベルのエージェントです	カスタムサブエージェント設定を含むSubAgentMiddlewareが必要です
長時間実行タスクエージェント	再起動後も状態を維持する必要がある、数時間または数日間にわたるワークフローです	チェックポインター + MemoryMiddlewareが必要です
オンデマンドスキルエージェント	ユーザーの依頼内容に応じて、異なるスキルセットを読み込むエージェントです	SkillsMiddleware + FilesystemBackendが必要です
マルチエージェントアーキテクチャ	分離されたタスク用のサブエージェントを起動するか、サブエージェントにアクセスできるエージェントです

すべてのDeep Agentsはcreate_deep_agent(model, tools=[...], ...)を使用します。次のスキル：deep-agents-core — Deep Agentsを選択したら、すぐに読み込んでください。

Deep Agentsに組み込まれたミドルウェア

6つのコンポーネントが最初から組み込まれています。最初の3つは常に有効で、残りはオプトインです。

ミドルウェア	常に有効？	エージェントに提供する機能
TodoListMiddleware	✓	write_todosツール — 複数ステップのタスク計画を追跡します
FilesystemMiddleware	✓	ls、read_file、write_file、edit_file、glob、grep
SubAgentMiddleware	✓	taskツール — 名前付きサブエージェントにサブタスクを委任します
SkillsMiddleware	オプトイン	スキルディレクトリからSKILL.mdファイルを必要に応じて読み込みます
MemoryMiddleware	オプトイン	Storeインスタンスを介して、セッションをまたいだ長期記憶を提供します
HumanInTheLoopMiddleware	オプトイン	実行を一時停止し、指定されたツール呼び出しの前に人間の承認を求めます

ミドルウェアは設定するものであり、実装するものではありません。

同じプロジェクト内でレイヤーを組み合わせることができます。最も一般的なパターンは、Deep Agentsをトップレベルのオーケストレーターとして使い、コンパイル済みのLangGraphグラフを専門サブエージェントとして登録する方法です。LangChainのツールとチェーンは、あらゆるレベルで使用できます。

---

ステップ3 — 依存関係をセットアップする

環境要件

	Python	TypeScript / Node
ランタイム	Python 3.10+	Node.js 20+
LangChain	1.0+ (LTS)	1.0+ (LTS)
LangSmith SDK	>= 0.3.0	>= 0.3.0

必ず LangChain 1.0+ を使用してください。 LangChain 0.3 は 2026 年 12 月までメンテナンスのみとなるため、新規プロジェクトでは使用しないでください。

---

コアパッケージ — 常に必要

**Python**

パッケージ	役割	バージョン
langchain	エージェント、チェーン、検索	>=1.0,<2.0
langchain-core	基本型とインターフェース	>=1.0,<2.0
langsmith	トレーシング、評価、データセット	>=0.3.0

**TypeScript**

パッケージ	役割	バージョン
@langchain/core	基本型とインターフェース（ピア依存関係 — 明示的にインストール）	^1.0.0
langchain	エージェント、チェーン、検索	^1.0.0
langsmith	トレーシング、評価、データセット	^0.3.0

---

オーケストレーション — フレームワークの選択に応じて追加

フレームワーク	Python	TypeScript
LangGraph	langgraph>=1.0,<2.0	@langchain/langgraph ^1.0.0
Deep Agents	deepagents（LangGraph に依存し、推移的依存関係としてインストール）	deepagents

---

モデルプロバイダー — 使用するものを選択

プロバイダー	Python	TypeScript
OpenAI	langchain-openai	@langchain/openai
Anthropic	langchain-anthropic	@langchain/anthropic
Google Gemini	langchain-google-genai	@langchain/google-genai
Mistral	langchain-mistralai	@langchain/mistralai
Groq	langchain-groq	@langchain/groq
Cohere	langchain-cohere	@langchain/cohere
AWS Bedrock	langchain-aws	@langchain/aws
Azure AI	langchain-azure-ai	@langchain/azure-openai
Ollama（ローカル）	langchain-ollama	@langchain/ollama
Hugging Face	langchain-huggingface	—
Fireworks AI	langchain-fireworks	—
Together AI	langchain-together	—

---

よく使うツールと検索 — 必要に応じて追加

パッケージ	追加される機能	備考
langchain-tavily / @langchain/tavily	Tavily ウェブ検索	互換性のため頻繁に更新されるので、常に最新版を使用
langchain-text-splitters	テキストのチャンク分割	セマンティックバージョニング。最新の状態を保つ
langchain-chroma / @langchain/community	Chroma ベクトルストア	専用の統合パッケージ。常に最新版を使用
langchain-pinecone / @langchain/pinecone	Pinecone ベクトルストア	専用の統合パッケージ。常に最新版を使用
langchain-qdrant / @langchain/qdrant	Qdrant ベクトルストア	専用の統合パッケージ。常に最新版を使用
faiss-cpu	FAISS ベクトルストア（Python のみ、ローカル）	langchain-community 経由
langchain-community / @langchain/community	1000 以上の統合のフォールバック	Python：セマンティックバージョニングではないため、マイナーバージョン系列を固定
langsmith[pytest]	pytest プラグイン	langsmith>=0.3.4 が必要

利用可能な場合は、langchain-community より専用の統合パッケージを優先してください。個別にバージョン管理されており、より安定しています。

### 依存関係のテンプレート LangChain エージェント — プロバイダーに依存しない出発点です。 ``` # requirements.txt langchain>=1.0,<2.0 langchain-core>=1.0,<2.0 langsmith>=0.3.0

Add your model provider:

langchain-openai | langchain-anthropic | langchain-google-genai | ...

Add tools/retrieval as needed:

langchain-tavily | langchain-chroma | langchain-text-splitters | ...

</python>
</ex-langchain-python>

<ex-langgraph-python>
<python>
LangGraph プロジェクト — プロバイダーに依存しない出発点です。

requirements.txt

langchain>=1.0,<2.0 langchain-core>=1.0,<2.0 langgraph>=1.0,<2.0 langsmith>=0.3.0

Add your model provider:

langchain-openai | langchain-anthropic | langchain-google-genai | ...

</python>
</ex-langgraph-python>

<ex-langgraph-typescript>
<typescript>
LangGraph プロジェクト — プロバイダーに依存しない出発点です。
```json
{
  "dependencies": {
    "@langchain/core": "^1.0.0",
    "langchain": "^1.0.0",
    "@langchain/langgraph": "^1.0.0",
    "langsmith": "^0.3.0"
  }
}

Deep Agents プロジェクト — プロバイダーに依存しない出発点です。 ``` # requirements.txt deepagents langchain>=1.0,<2.0 langchain-core>=1.0,<2.0 langsmith>=0.3.0

Add your model provider:

langchain-openai | langchain-anthropic | langchain-google-genai | ...

</python>
</ex-deepagents-python>

<ex-deepagents-typescript>
<typescript>
Deep Agents プロジェクト — プロバイダーに依存しない出発点です。
```json
{
  "dependencies": {
    "deepagents": "latest",
    "@langchain/core": "^1.0.0",
    "langchain": "^1.0.0",
    "langsmith": "^0.3.0"
  }
}

---

ステップ 4 — 環境変数を設定する

```bash # LangSmith — always recommended for observability LANGSMITH_API_KEY= LANGSMITH_PROJECT= # optional, defaults to "default"

Model provider — set the one(s) you use

OPENAI_API_KEY= ANTHROPIC_API_KEY= GOOGLE_API_KEY= MISTRAL_API_KEY= GROQ_API_KEY= COHERE_API_KEY= FIREWORKS_API_KEY= TOGETHER_API_KEY= HUGGINGFACEHUB_API_TOKEN=

Common tool/retrieval services

TAVILY_API_KEY= PINECONE_API_KEY=

</environment-variables>

---

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

上で選択したフレームワークとアーキタイプに基づいて、コードを書く前に**今すぐ**次のスキルを呼び出してください。

<next-skills>

### LangChain を選択した場合

| アーキタイプ | 次に読み込むもの |
|----------------|-----------|
| あらゆる LangChain エージェント（QA ボット、SQL、検索、RAG、ツール呼び出し） | **`langchain-fundamentals`** — 常に読み込みます |
| 外部ツール／パッケージを追加する場合（Tavily、Pinecone など） | **`langchain-dependencies`** — パッケージのパターンとバージョンのガイダンス |
| ストリーミングまたは非同期応答が必要な場合 | **`langchain-fundamentals`**、次に `langgraph-fundamentals` |

### LangGraph を選択した場合

| アーキタイプ | 次に読み込むもの |
|----------------|-----------|
| あらゆる LangGraph グラフ | **`langgraph-fundamentals`** — 常に読み込みます |
| 承認パイプライン、HITL、または一時停止／再開 | **`langgraph-fundamentals`** + `langgraph-human-in-the-loop` |
| 再起動後も保持する必要がある状態、またはスレッドをまたぐメモリ | **`langgraph-persistence`** |
| トークン単位のストリーミング出力 | **`langgraph-fundamentals`** |

### Deep Agents を選択した場合

**すべての Deep Agents プロジェクトで、必須の出発点である `deep-agents-core` を必ず最初に読み込んでください。**

| アーキタイプ | 次に読み込むもの（`deep-agents-core` の後） |
|----------------|--------------------------------------|
| リサーチアシスタント — 専門サブエージェントに処理を委任する | **`deep-agents-orchestration`** — サブエージェントの設定、TodoList、HITL |
| パーソナルアシスタント — セッションをまたいでユーザーを記憶する | **`deep-agents-memory`** — MemoryMiddleware、Store バックエンド |
| コーディングアシスタント — ファイルの読み書きやリファクタリングの計画を行う | `deep-agents-core` で十分です。HITL を使用する場合は `deep-agents-orchestration` を追加してください |
| オーケストレーター — 複数の名前付きサブエージェント間で処理を振り分ける | **`deep-agents-orchestration`** — SubAgentMiddleware のパターン |
| 長時間実行タスクエージェント — 再起動後も処理を継続する | **`deep-agents-memory`** + `deep-agents-orchestration` |
| オンデマンドスキルエージェント | `deep-agents-core` で SkillsMiddleware のセットアップをカバーします |
</next-skills>