zoujindouGithub - Deep Agents（顶层，运行框架/Harness）—— 基于 LangChain + LangGraph 构建的开箱即用工具包。内置规划（Planning）、文件管理、子智能体派生（Subagent Spawning）和记忆能力。
- LangGraph（中层，运行时/Runtime）—— 用于持久化执行、自定义控制流和有状态工作流的底层编排工具。LangChain 智能体运行在 LangGraph 之上。
- LangChain（底层，基础框架/Framework）—— 提供模型、工具和智能体循环的抽象。与模型提供商无关，最容易上手。
- LangSmith（横切层）—— 可观测性和评估平台。与框架无关；强烈建议与上述任何工具搭配使用。
上层依赖下层，但你无需直接操作下层。Deep Agents 无需编写图代码即可为你提供 LangGraph 的持久化执行能力。LangChain 无需管理图的边即可为你提供模型和工具支持。
步骤 1 — 选择你的工具
按顺序评估以下条件，并在遇到第一个匹配项时停止：
- 如果任务需要规划、跨长会话的文件管理、持久记忆、子智能体委派或按需加载技能 → Deep Agents
- 否则，如果任务需要自定义控制流（确定性循环、分支逻辑） → LangGraph
- 否则，如果是具有固定工具集的单一用途智能体 → LangChain（
create_agent函数） - 否则，如果它是纯模型调用、检索管道或没有智能体循环的简单提示词链 → LangChain（直接使用模型 / 链）
这就是你的层级（layer）。但这还没有结束：稍后在步骤 4 中，你在编写任何智能体代码之前必须加载特定于该层级的技能。
工具特性简介
LangChain — 智能体框架
最适用于：
- 拥有固定工具集的单一用途智能体
- RAG 管道和文档问答
- 模型调用、提示词模板、结构化输出
不适用的场景：
- 智能体需要跨多个步骤进行规划或管理庞大的上下文
- 控制流包含条件分支、迭代循环或并行执行
- 状态必须跨会话持久化
所有 LangChain 智能体均使用 create_agent(model, tools=[...])。
LangGraph — 智能体运行时
最适用于：
- 自定义控制流 —— 确定性循环、反思机制、并行扇出
- 结合了确定性步骤和智能体步骤的复杂工作流
- 具备精确中断和恢复点的人机协作（Human-in-the-loop）
- 必须在故障后恢复或跨越长时间会话的状态
不适用的场景：
- 你需要开箱即用的规划、文件管理和子智能体委派（此时请使用 Deep Agents）
- 工作流足够简单，仅需直接的工具调用循环
所有 LangGraph 图均使用 StateGraph(State) 以及显式的节点（nodes）、边（edges）和条件边（conditional edges）。
Deep Agents — 智能体运行框架
最适用于：
- 需要规划和任务分解的长时间运行任务
- 在整个会话中需要读取、写入和管理文件的智能体
- 将子任务委派给专门的子智能体
- 跨会话的持久记忆
- 按需加载特定领域的技能
不适用的场景：
- 任务足够简单，单一用途智能体即可胜任
- 你需要对图中的每条边进行精细的手工控制（此时请直接使用 LangGraph）
所有 Deep Agents 均使用 create_deep_agent(model, tools=[...])。
混合使用各层
这些工具是分层的，因此它们可以在同一个项目中组合使用。常见模式包括：
- Deep Agents 编排器 → LangGraph 子智能体 —— 当主智能体需要规划和记忆能力，但其中一个子任务需要确定性图结构时。
- 封装为工具或子智能体的 LangGraph 图 —— 当专门的管道（例如 RAG、反思循环）被更高级别的智能体调用时。
编译后的 LangGraph 图可以注册为 Deep Agents 内部的具名子智能体 —— 编排器通过 task 工具向其委派任务，而无需了解其内部结构。LangChain 工具和检索器可以在 LangGraph 节点和 Deep Agents 工具中自由使用。
步骤 2 — 配置环境变量
始终设置以下变量以启用可观测性。这些是当前最新的 LangSmith 环境变量名称。请原样复制。旧名称已不再有效。
模型提供商和特定工具的密钥（ANTHROPIC_API_KEY、OPENAI_API_KEY、TAVILY_API_KEY 等）取决于你的技术栈 —— 请根据需要进行设置。
步骤 3 — 文档使用指南
所有文档均托管在 docs.langchain.com，分为两个顶级板块：
- OSS — LangChain、LangGraph、Deep Agents。提供并行的 Python（
/oss/python/）和 TypeScript（/oss/javascript/）文档树。 - LangSmith — 可观测性、评估、部署、提示词工程。
每个产品都有自己的页面树：概述（overview）→ 快速入门（quickstart）→ 操作指南（how-to guides）→ 参考文档（reference）。
官方推荐落地页
建议从以下页面开始，而不是从根目录遍历搜索（如需 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 # 浏览 Python 文档结构
tree /oss/javascript -L 2 # 浏览并行的 TypeScript 文档结构
cat /oss/python/langchain/quickstart.mdx # 读取特定页面
rg -il "checkpointer" /oss/python/langgraph/ # 按关键词搜索
如果 MCP 服务器不可用，请使用 llms.txt 索引：
- 获取
https://docs.langchain.com/llms.txt—— 包含所有页面及其描述的结构化列表 - 确定与问题最相关的 2–4 个页面
- 直接获取这些页面以获取准确、最新的内容
始终优先获取实时文档，而不是依赖训练数据中的知识 —— 这些库迭代非常快，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；单独的基础指南（primer）并不包含这些具体细节。
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— 跨会话持久记忆