OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add langchain-ai/skills-benchmarks --skill langchain-oss-primer
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.
npx skills add langchain-ai/skills-benchmarks --skill langchain-oss-primer
It answers three questions every project must resolve upfront:
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.
The three frameworks are layered, not competing. Each builds on the one below:
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.
Once you've chosen a framework, match your use case to the right API and pattern.
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.
StateGraphBest 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.
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.
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.| 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.
| 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 |
| 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 |
| 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 |
| 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 | — |
| 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-communitywhen one exists — they are independently versioned and more stable.
langchain>=1.0,<2.0 langchain-core>=1.0,<2.0 langgraph>=1.0,<2.0 langsmith>=0.3.0
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=
TAVILY_API_KEY= PINECONE_API_KEY=