langchain-oss-primer

name	langchain-oss-primer
description	ALWAYS START HERE for any LangChain, Deep Agents, or LangGraph agent building project. Required starting point before choosing other skills or writing any code. Covers framework selection (LangChain vs LangGraph vs Deep Agents), agent archetypes, dependency setup, and which skills to load next based on your decisions.

**Always load this skill first.** This is the required starting point for any LangChain open source agent project — before choosing other skills, before writing code, before installing packages.

It answers three questions every project must resolve upfront:

1. Which framework? — LangChain, LangGraph, or Deep Agents
2. Which agent archetype? — maps your use case to the right API and patterns
3. What to install and which skills to load next

Load this skill first. Once you've decided on a framework and agent type, follow the "Next Skills" section at the bottom — it tells you exactly which skills to invoke next based on your choices.

---

Step 1 — Pick Your Framework

The three frameworks are layered, not competing. Each builds on the one below:

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

Answer these questions in order:

Question	Yes →	No →
User needs or wants planning, persistent memory, complex task management, long-running tasks, out-of-the-box file management, on-demand skills, or built-in middleware, subagents, easy expansion capabilities?	Deep Agents	↓
Needs custom control flow — specified loops, branching, deterministic parallel workers, or manually instrumented human-in-the-loop?	LangGraph	↓
Single-purpose agent with a fixed set of tools?	LangChain (create_agent)	↓
Simple prompt pipeline or retrieval chain with no agent loop?	LangChain (direct model / chain)	—

Higher layers depend on lower ones only when necessary — you can mix them. A LangGraph graph can be a subagent inside Deep Agents; LangChain tools work inside both.

	LangChain	LangGraph	Deep Agents
Control flow	Fixed (tool loop)	Custom (graph)	Managed (middleware)
Middleware	Callbacks only	✗ None	✓ Explicit, configurable
Planning	✗	Manual	✓ TodoListMiddleware
File management	✗	Manual	✓ FilesystemMiddleware
Persistent memory	✗	With checkpointer	✓ MemoryMiddleware
Subagent delegation	✗	Manual	✓ SubAgentMiddleware
On-demand skills	✗	✗	✓ SkillsMiddleware
Human-in-the-loop	✗	Manual interrupt	✓ HumanInTheLoopMiddleware
Custom graph edges	✗	✓ Full control	Limited
Setup complexity	Low	Medium	Low

Middleware is a concept specific to Deep Agents (explicit middleware layer). LangGraph has no middleware — behavior is wired directly into nodes and edges. If a user asks for built-in hooks or automatic middleware, route to Deep Agents.

---

Step 2 — Pick Your Agent Archetype

Once you've chosen a framework, match your use case to the right API and pattern.

LangChain — use create_agent()

Best for single-purpose agents in a ReACT style with a fixed tool set. No built-in planning, memory management, or delegation.

Archetype	Description	Key tools
QA / Chatbot	Answer questions, summarise, classify. One job, done well.	LLM + optional retrieval
SQL Agent	Query a database, return structured results	SQLDatabase, create_agent
Search Agent	Look up information, return findings	TavilySearchResults, DuckDuckGoSearch
RAG Agent	Retrieve from a vector store, ground answers in documents	retriever tool + create_agent
Data Analysis Agent	Load, transform, and summarise structured data	PythonREPL, pandas tools
Tool-calling Agent	Call APIs, run code, or chain arbitrary tools	custom @tool functions

All LangChain agents use create_agent(model, tools=[...]). Next skill: langchain-fundamentals.

LangGraph — use StateGraph

Best when you need explicit, deterministic control flow.

Archetype	Description	Key pattern
Deterministic Parallel Workflows	Fan out to multiple nodes, collect results, merge	parallel edges → aggregation node
Multi-stage Pipeline	Extract → Transform → Load with typed state	TypedDict state + sequential nodes
Branching Classifier	Route inputs to different handlers based on content	conditional edges + classifer node
Reflection Loop	Generate → Critique → Revise cycle with explicit exit	cycle edges + iteration counter
Custom HITL	Complex human-in-the-loop with structured review and conditional edges	interrupt_before/interrupt_after + Command resume

LangGraph agents use StateGraph(State) with explicit add_node, add_edge, add_conditional_edges. Next skill: langgraph-fundamentals.

Deep Agents — use create_deep_agent()

Best when the agent needs to manage its own work: planning tasks, remembering users across sessions, delegating to specialists, or managing files autonomously.

Archetype	Description	Why Deep Agents
Research Assistant	Receives an open-ended research brief, breaks it into subtasks, delegates to specialist subagents, writes up findings	Needs SubAgentMiddleware for delegation + TodoListMiddleware for planning
Personal Assistant	Remembers user preferences, ongoing projects, and context across multiple sessions	Needs MemoryMiddleware (Store) for cross-session persistence
Coding Assistant	Reads codebases, writes files, plans refactors across many steps, optionally asks for approval before writes	Needs FilesystemMiddleware + TodoListMiddleware + optional HITL
Orchestrator	Top-level agent that routes work to 2+ specialized subagents (researcher, coder, writer…)	Needs SubAgentMiddleware with custom subagent configs
Long-running Task Agent	Multi-hour or multi-day workflows where state must survive restarts	Needs checkpointer + MemoryMiddleware
On-demand Skills Agent	Agent that loads different skill sets depending on what the user asks	Needs SkillsMiddleware + FilesystemBackend
Multi Agent Architecture	Agent that spawns or has access to subagents for isolated tasks

All Deep Agents use create_deep_agent(model, tools=[...], ...). Next skill: deep-agents-core — load it immediately after deciding on Deep Agents.

Deep Agents built-in middleware

Six components pre-wired out of the box. First three are always active; the rest are opt-in:

Middleware	Always on?	What it gives the agent
TodoListMiddleware	✓	write_todos tool — tracks multi-step task plans
FilesystemMiddleware	✓	ls, read_file, write_file, edit_file, glob, grep
SubAgentMiddleware	✓	task tool — delegates subtasks to named subagents
SkillsMiddleware	Opt-in	Loads SKILL.md files on demand from a skills directory
MemoryMiddleware	Opt-in	Long-term memory across sessions via a Store instance
HumanInTheLoopMiddleware	Opt-in	Pauses execution and requests human approval before specified tool calls

You configure middleware — you don't implement it.

You can combine layers in the same project. The most common pattern: Deep Agents as the top-level orchestrator, with a compiled LangGraph graph registered as a specialized subagent. LangChain tools and chains are usable at every level.

---

Step 3 — Set Up Your Dependencies

Environment requirements

	Python	TypeScript / Node
Runtime	Python 3.10+	Node.js 20+
LangChain	1.0+ (LTS)	1.0+ (LTS)
LangSmith SDK	>= 0.3.0	>= 0.3.0

Always use LangChain 1.0+. LangChain 0.3 is maintenance-only until December 2026 — do not start new projects on it.

---

Core packages — always required

**Python**

Package	Role	Version
langchain	Agents, chains, retrieval	>=1.0,<2.0
langchain-core	Base types & interfaces	>=1.0,<2.0
langsmith	Tracing, evaluation, datasets	>=0.3.0

**TypeScript**

Package	Role	Version
@langchain/core	Base types & interfaces (peer dep — install explicitly)	^1.0.0
langchain	Agents, chains, retrieval	^1.0.0
langsmith	Tracing, evaluation, datasets	^0.3.0

---

Orchestration — add based on your framework choice

Framework	Python	TypeScript
LangGraph	langgraph>=1.0,<2.0	@langchain/langgraph ^1.0.0
Deep Agents	deepagents (depends on LangGraph; installs it as a transitive dep)	deepagents

---

Model providers — pick the one(s) you use

Provider	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 (local)	langchain-ollama	@langchain/ollama
Hugging Face	langchain-huggingface	—
Fireworks AI	langchain-fireworks	—
Together AI	langchain-together	—

---

Common tools & retrieval — add as needed

Package	Adds	Notes
langchain-tavily / @langchain/tavily	Tavily web search	Keep at latest; frequently updated for compatibility
langchain-text-splitters	Text chunking	Semver; keep current
langchain-chroma / @langchain/community	Chroma vector store	Dedicated integration package; keep at latest
langchain-pinecone / @langchain/pinecone	Pinecone vector store	Dedicated integration package; keep at latest
langchain-qdrant / @langchain/qdrant	Qdrant vector store	Dedicated integration package; keep at latest
faiss-cpu	FAISS vector store (Python only, local)	Via langchain-community
langchain-community / @langchain/community	1000+ integrations fallback	Python: NOT semver — pin to minor series
langsmith[pytest]	pytest plugin	Requires langsmith>=0.3.4

Prefer dedicated integration packages over langchain-community when one exists — they are independently versioned and more stable.

---

Dependency templates

LangChain agent — provider-agnostic starting point. ``` # 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 project — provider-agnostic starting point.

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 project — provider-agnostic starting point.
```json
{
  "dependencies": {
    "@langchain/core": "^1.0.0",
    "langchain": "^1.0.0",
    "@langchain/langgraph": "^1.0.0",
    "langsmith": "^0.3.0"
  }
}

Deep Agents project — provider-agnostic starting point. ``` # 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 project — provider-agnostic starting point.
```json
{
  "dependencies": {
    "deepagents": "latest",
    "@langchain/core": "^1.0.0",
    "langchain": "^1.0.0",
    "langsmith": "^0.3.0"
  }
}

---

Step 4 — Set Your Environment Variables

```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>

---

## Step 5 — Load the Right Skill Next

Based on the framework and archetype you chose above, invoke these skills **now** before writing any code:

<next-skills>

### If you chose LangChain

| Your archetype | Load next |
|----------------|-----------|
| Any LangChain agent (QA bot, SQL, search, RAG, tool-calling) | **`langchain-fundamentals`** — always |
| Adding external tools/packages (Tavily, Pinecone, etc.) | **`langchain-dependencies`** — package patterns and version guidance |
| Need streaming or async responses | **`langchain-fundamentals`** then `langgraph-fundamentals` |

### If you chose LangGraph

| Your archetype | Load next |
|----------------|-----------|
| Any LangGraph graph | **`langgraph-fundamentals`** — always |
| Approval pipeline, HITL, or pause/resume | **`langgraph-fundamentals`** + `langgraph-human-in-the-loop` |
| State that must survive restarts or cross-thread memory | **`langgraph-persistence`** |
| Streaming output token by token | **`langgraph-fundamentals`** |

### If you chose Deep Agents

**Always load `deep-agents-core` first — it is the mandatory starting point for any Deep Agents project.**

| Your archetype | Load next (after `deep-agents-core`) |
|----------------|--------------------------------------|
| Research Assistant — delegates to specialist subagents | **`deep-agents-orchestration`** — subagent config, TodoList, HITL |
| Personal Assistant — remembers users across sessions | **`deep-agents-memory`** — MemoryMiddleware, Store backends |
| Coding Assistant — reads/writes files, plans refactors | `deep-agents-core` is sufficient; add `deep-agents-orchestration` if using HITL |
| Orchestrator — routes work across multiple named subagents | **`deep-agents-orchestration`** — SubAgentMiddleware patterns |
| Long-running task agent — survives restarts | **`deep-agents-memory`** + `deep-agents-orchestration` |
| On-demand skills agent | `deep-agents-core` covers SkillsMiddleware setup |
</next-skills>