ecosystem-primer

LangChain Inc. 维护着三层开源工具，用于构建 Agent，并提供 LangSmith 进行可观测性支持。整个技术栈从上到下如下：

• Deep Agents（顶层，harness）——基于 LangChain + LangGraph 构建的开箱即用工具包。内置规划、文件管理、子 Agent 调用和记忆功能。
• LangGraph（中间层，runtime）——提供底层编排能力，支持持久化执行、自定义控制流和有状态工作流。LangChain Agent 运行在 LangGraph 之上。
• LangChain（底层，framework）——提供模型、工具和 Agent 循环的抽象。与具体提供商无关，最容易上手。
• LangSmith（跨层）——可观测性与评估平台。与框架无关；始终建议与上述任一工具搭配使用。

较高层依赖较低层，但你不必直接使用较低层。Deep Agents 可让你使用 LangGraph 的持久化执行能力，而无需编写图代码。LangChain 可让你使用模型和工具，而无需管理图边。

---

第 1 步 — 选择工具

按顺序评估以下条件，并在找到第一个匹配项时停止：

1. 如果任务需要规划、在长时间会话中管理文件、持久记忆、委派给子 Agent，或按需加载技能 → Deep Agents
2. 否则，如果任务需要自定义控制流（确定性循环、分支逻辑）→ LangGraph
3. 否则，如果任务是只有一组固定工具的单一用途 Agent → LangChain（create_agent 函数）
4. 否则，如果任务只是调用模型、检索流程，或不含 Agent 循环的简单提示词链 → LangChain（直接调用模型／链）

这就是你的层级。但还没结束：在第 4 步中，编写任何 Agent 代码之前，必须加载该层专用的技能。

---

工具简介

LangChain — Agent 框架

最适合：

• 只有一组固定工具的单一用途 Agent
• RAG 流程和文档问答
• 模型调用、提示词模板、结构化输出

不太适合：

• Agent 需要跨许多步骤进行规划或管理大量上下文
• 控制流包含条件、迭代或并行逻辑
• 状态必须跨会话持久保存

所有 LangChain Agent 都使用 create_agent(model, tools=[...])。

LangGraph — Agent 运行时

最适合：

• 自定义控制流——确定性循环、反思循环、并行扇出
• 结合确定性步骤和 Agent 式步骤的复杂工作流
• 需要精确设置中断点和恢复点的人工参与流程
• 必须在故障后保留或跨越长时间会话的状态

不太适合：

• 需要开箱即用的规划、文件管理和子 Agent 委派功能（请改用 Deep Agents）
• 工作流足够简单，可以使用直接的工具循环

所有 LangGraph 图都使用 StateGraph(State)，并显式定义节点、边和条件边。

Deep Agents — Agent harness

最适合：

• 需要规划和拆解任务的长时间运行任务
• 需要在会话期间读取、写入和管理文件的 Agent
• 将子任务委派给专业子 Agent
• 跨会话持久保存记忆
• 按需加载特定领域的技能

不太适合：

• 任务足够简单，可以使用单一用途 Agent
• 需要精确地手动控制每一条图边（请直接使用 LangGraph）

所有 Deep Agents 都使用 create_deep_agent(model, tools=[...])。

## 混合层

这些工具采用分层设计，因此可以在同一个项目中组合使用。常见模式：

• Deep Agents 编排器 → LangGraph 子 Agent — 当主 Agent 需要规划和记忆，但某个子任务需要确定性图时。
• 将 LangGraph 图封装为工具或子 Agent — 当更广泛的 Agent 会调用专用流水线（例如 RAG、反思循环）时。

已编译的 LangGraph 图可以注册为 Deep Agents 中的具名子 Agent — 编排器通过 task 工具将任务委派给它，而无需了解其内部结构。LangChain 工具和检索器可以在 LangGraph 节点和 Deep Agents 工具中自由使用。

---

第 2 步 — 设置环境变量

始终设置这些变量以实现可观测性。以下是当前的 LangSmith 环境变量名称。请原样复制。旧名称已不再有效。

LANGSMITH_API_KEY= LANGSMITH_TRACING=true LANGSMITH_PROJECT=

模型提供商和特定工具的密钥（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 — 可观测性、评估、部署、提示词工程。

每个产品都有自己的页面树：概览 → 快速入门 → 操作指南 → 参考文档。

规范入口页面

请从这里开始，而不要从根目录逐层搜索（将 python 替换为 javascript 即可查看 TypeScript 文档）：

• LangChain — /oss/python/langchain/overview
• LangGraph — /oss/python/langgraph/overview
• Deep Agents — /oss/python/deepagents/overview
• LangSmith — /langsmith/home（不区分语言）

在 Agent 环境中访问文档

如果已连接 LangChain Docs MCP 服务（可使用 mcp__docs-langchain__* 工具），请直接查询：

tree /oss/python -L 2                        # explore Python structure
tree /oss/javascript -L 2                    # parallel TypeScript structure
cat /oss/python/langchain/quickstart.mdx     # read a specific page
rg -il "checkpointer" /oss/python/langgraph/ # search by keyword

如果 MCP 服务不可用，请使用 llms.txt 索引：

1. 获取 https://docs.langchain.com/llms.txt — 包含所有页面及其说明的结构化列表
2. 找出与问题最相关的 2–4 个页面
3. 直接获取这些页面，以取得准确且最新的内容

始终优先获取实时文档，而不要依赖训练数据中的知识 — 这些库发展迅速，API 也经常变化。

---

第 4 步 — 接下来加载合适的 Skill

如果用户只需要一个最精简的本地可用 Agent（新项目、工具框架、提供商密钥），请先加载匹配的快速入门：

• LangChain → langchain-python-quickstart 或 langchain-typescript-quickstart
• LangGraph → langgraph-python-quickstart 或 langgraph-typescript-quickstart
• Deep Agents → deepagents-python-quickstart 或 deepagents-typescript-quickstart

否则，请加载与第 1 步中的层相匹配的下列 Skill。这是必需步骤 — 特定层的 Skill 包含当前 API；仅使用入门指南还不够。

LangChain

• langchain-fundamentals — 构建任何 LangChain Agent
• 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 — 子 Agent 委派或编排
• deep-agents-memory — 跨会话持久记忆