langchain-oss-primer

**始终先加载此技能。** 这是任何 LangChain 开源 Agent 项目的必备起点——在选择其他技能、编写代码和安装软件包之前。

它会回答每个项目都必须提前明确的三个问题：

1. 选择哪个框架？ — LangChain、LangGraph 还是 Deep Agents
2. 选择哪种 Agent 原型？ — 根据你的用例选择合适的 API 和模式
3. 需要安装什么，以及接下来加载哪些技能？

首先加载此技能。确定框架和 Agent 类型后，请遵循底部的“后续技能”部分——它会根据你的选择准确指出接下来要调用哪些技能。

---

步骤 1 — 选择框架

这三个框架是分层的，而非相互竞争。每一层都构建在下一层之上：

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

请按顺序回答以下问题：

问题	是 →	否 →
用户是否需要或希望具备规划、持久记忆、复杂任务管理、长时间运行的任务、开箱即用的文件管理、按需技能，或内置中间件、子 Agent、轻松扩展等能力？	Deep Agents	↓
是否需要自定义控制流——指定循环、分支、确定性并行工作进程，或手动接入人在回路？	LangGraph	↓
是否是工具集固定的单一用途 Agent？	LangChain（create_agent）	↓
是否是没有 Agent 循环的简单提示词流水线或检索链？	LangChain（直接调用模型／链）	—

只有在必要时，较高层才依赖较低层——你可以混合使用。LangGraph 图可以作为 Deep Agents 中的子 Agent；LangChain 工具也能在两者中使用。

	LangChain	LangGraph	Deep Agents
控制流	固定（工具循环）	自定义（图）	托管（中间件）
中间件	仅回调	✗ 无	✓ 显式、可配置
规划	✗	手动	✓ TodoListMiddleware
文件管理	✗	手动	✓ FilesystemMiddleware
持久记忆	✗	使用 checkpointer	✓ MemoryMiddleware
子 Agent 委派	✗	手动	✓ SubAgentMiddleware
按需技能	✗	✗	✓ SkillsMiddleware
人在回路	✗	手动中断	✓ HumanInTheLoopMiddleware
自定义图边	✗	✓ 完全控制	有限
设置复杂度	低	中	低

中间件是 Deep Agents 特有的概念（显式的中间件层）。LangGraph 没有中间件——其行为直接连接在节点和边上。如果用户要求内置钩子或自动中间件，请引导至 Deep Agents。

---

步骤 2 — 选择 Agent 原型

选定框架后，根据你的用例匹配合适的 API 和模式。

LangChain — 使用 create_agent()

最适合采用 ReACT 风格、工具集固定的单一用途 Agent。不内置规划、记忆管理或委派功能。

原型	描述	关键工具
问答／聊天机器人	回答问题、总结、分类。专注做好一项工作。	大模型 + 可选检索
SQL Agent	查询数据库并返回结构化结果	SQLDatabase、create_agent
搜索 Agent	查找信息并返回结果	TavilySearchResults、DuckDuckGoSearch
RAG Agent	从向量存储中检索内容，并基于文档生成答案	检索器工具 + create_agent
数据分析 Agent	加载、转换并总结结构化数据	PythonREPL、pandas 工具
工具调用 Agent	调用 API、运行代码或串联任意工具	自定义 @tool 函数

所有 LangChain Agent 均使用 create_agent(model, tools=[...])。下一项技能：langchain-fundamentals。

### LangGraph — 使用 `StateGraph`

适用于需要明确、确定性控制流的场景。

架构模式	描述	关键模式
确定性并行工作流	将任务分发到多个节点，收集结果并合并	并行边 → 汇总节点
多阶段流水线	使用带类型的状态执行提取 → 转换 → 加载	TypedDict 状态 + 顺序节点
分支分类器	根据内容将输入路由到不同的处理器	条件边 + 分类器节点
反思循环	执行生成 → 批评 → 修订循环，并明确退出条件	循环边 + 迭代计数器
自定义 HITL	使用结构化审查和条件边实现复杂的人机协作	interrupt_before/interrupt_after + Command 恢复

LangGraph Agent 使用 StateGraph(State)，并显式调用 add_node、add_edge、add_conditional_edges。下一项技能：langgraph-fundamentals。

Deep Agents — 使用 create_deep_agent()

适用于 Agent 需要管理自身工作的场景：规划任务、跨会话记住用户、委派给专业 Agent，或自主管理文件。

架构模式	描述	Deep Agents 的优势
研究助手	接收开放式研究任务，将其拆分为子任务，委派给专业子 Agent，并整理研究结果	需要 SubAgentMiddleware 来委派任务，并使用 TodoListMiddleware 来规划
个人助手	跨多个会话记住用户偏好、进行中的项目和上下文	需要 MemoryMiddleware（Store）来实现跨会话持久化
编码助手	读取代码库、编写文件、规划跨多个步骤的重构，并可选择在写入前请求批准	需要 FilesystemMiddleware + TodoListMiddleware + 可选的 HITL
编排器	将工作路由给 2 个或更多专业子 Agent（研究员、编码员、撰稿人……）的顶层 Agent	需要使用自定义子 Agent 配置的 SubAgentMiddleware
长时间运行的任务 Agent	状态必须能够在重启后保留的多小时或多天工作流	需要 checkpointer + MemoryMiddleware
按需技能 Agent	根据用户请求加载不同技能集的 Agent	需要 SkillsMiddleware + FilesystemBackend
多 Agent 架构	可生成子 Agent，或能够访问子 Agent 来执行隔离任务的 Agent

所有 Deep Agents 都使用 create_deep_agent(model, tools=[...], ...)。下一项技能：deep-agents-core — 确定使用 Deep Agents 后立即加载。

Deep Agents 内置中间件

开箱即用、预先配置好的六个组件。前三个始终启用，其余为可选项：

中间件	始终启用？	提供给 Agent 的功能
TodoListMiddleware	✓	write_todos 工具 — 跟踪多步骤任务计划
FilesystemMiddleware	✓	ls、read_file、write_file、edit_file、glob、grep
SubAgentMiddleware	✓	task 工具 — 将子任务委派给指定的子 Agent
SkillsMiddleware	可选	按需从技能目录加载 SKILL.md 文件
MemoryMiddleware	可选	通过 Store 实例实现跨会话的长期记忆
HumanInTheLoopMiddleware	可选	暂停执行，并在调用指定工具前请求人工批准

你只需配置中间件，无需自行实现。

你可以在同一个项目中组合不同层级。最常见的模式是：Deep Agents 作为顶层编排器，并将已编译的 LangGraph 图注册为专业子 Agent。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**

Package	用途	版本
langchain	Agent、链、检索	>=1.0,<2.0
langchain-core	基础类型和接口	>=1.0,<2.0
langsmith	跟踪、评估、数据集	>=0.3.0

**TypeScript**

Package	用途	版本
@langchain/core	基础类型和接口（对等依赖 — 需显式安装）	^1.0.0
langchain	Agent、链、检索	^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	文本分块	遵循 SemVer；保持为最新版本
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：不遵循 SemVer — 固定到次版本系列
langsmith[pytest]	pytest 插件	需要 langsmith>=0.3.4

如果存在专用集成包，优先选择它，而不是 langchain-community——这些包有独立的版本管理，稳定性更高。

### 依赖模板 LangChain Agent——与提供商无关的起点。 ``` # 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 Agent（问答机器人、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`** |
| 逐个 Token 流式输出 | **`langgraph-fundamentals`** |

### 如果你选择了 Deep Agents

**始终先加载 `deep-agents-core`——它是任何 Deep Agents 项目的必备起点。**

| 你的范型 | 接下来加载（在 `deep-agents-core` 之后） |
|----------------|--------------------------------------|
| 研究助手——委派任务给专业子 Agent | **`deep-agents-orchestration`**——子 Agent 配置、TodoList、HITL |
| 个人助手——跨会话记住用户信息 | **`deep-agents-memory`**——MemoryMiddleware、Store 后端 |
| 编码助手——读取/写入文件、规划重构 | `deep-agents-core` 已足够；如果使用 HITL，则添加 `deep-agents-orchestration` |
| 编排器——在多个命名子 Agent 之间分派工作 | **`deep-agents-orchestration`**——SubAgentMiddleware 模式 |
| 长时间运行的任务 Agent——重启后仍可继续 | **`deep-agents-memory`** + `deep-agents-orchestration` |
| 按需技能 Agent | `deep-agents-core` 涵盖 SkillsMiddleware 的设置 |
</next-skills>