ecosystem-primer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<overview> LangChain Inc. maintains three layered open-source tools for building agents, plus LangSmith for observability. The stack, top-down:

Deep Agents (top layer, harness) — batteries-included toolkit built on LangChain + LangGraph. Ships with planning, file management, subagent spawning, and memory out of the box.
LangGraph (middle layer, runtime) — low-level orchestration for durable execution, custom control flow, and stateful workflows. LangChain agents run on top of LangGraph.
LangChain (bottom layer, framework) — abstractions for models, tools, and the agent loop. Provider-agnostic, easiest to start with.
LangSmith (cross-cutting) — observability and evaluation platform. Framework-agnostic; always recommended alongside any of the above.

Higher layers depend on lower ones, but you don't need to use lower layers directly. Deep Agents gives you LangGraph's durable execution without writing graph code. LangChain gives you models and tools without managing graph edges. </overview>

<overview> LangChain Inc. 维护着三个用于构建Agent的分层开源工具，以及用于可观测性的LangSmith。从顶层到底层的技术栈如下：

Deep Agents（顶层，工具集）——基于LangChain + LangGraph构建的开箱即用工具包，内置规划、文件管理、子Agent生成和记忆功能。
LangGraph（中层，运行时）——用于持久化执行、自定义控制流和有状态工作流的底层编排工具。LangChain Agent运行在LangGraph之上。
LangChain（底层，框架）——针对模型、工具和Agent循环的抽象层。与供应商无关，最易于入门。
LangSmith（跨层工具）——可观测性与评估平台。与框架无关；搭配上述任意工具使用时均推荐启用。

高层工具依赖底层工具，但你无需直接使用底层工具。Deep Agents无需编写图代码即可让你享受LangGraph的持久化执行能力。LangChain无需管理图边缘即可为你提供模型和工具。 </overview>

Step 1 — Choose Your Tool

步骤1 — 选择你的工具

<decision-table>

Evaluate these conditions in order and stop at the first match:

If the task needs planning, file management across a long session, persistent memory, subagent delegation, or on-demand skills → Deep Agents
Else, if the task needs custom control flow (deterministic loops, branching logic) → LangGraph
Else, if it's a single-purpose agent with a fixed set of tools → LangChain (
```
create_agent
```
function)
Else, if it's a pure model call, retrieval pipeline, or simple prompt chain with no agent loop → LangChain (direct model / chain)

This is your layer. BUT you are not done: later in Step 4, you MUST load the layer-specific skill before writing any agent code.

</decision-table>

<decision-table>

按顺序评估以下条件，匹配到第一个符合项后停止：

如果任务需要规划、长会话跨文件管理、持久化记忆、子Agent委托或按需加载技能 → Deep Agents
否则，如果任务需要自定义控制流（确定性循环、分支逻辑） → LangGraph
否则，如果是具有固定工具集的单一用途Agent → LangChain（
```
create_agent
```
函数）
否则，如果是纯模型调用、检索管道或无Agent循环的简单提示链 → LangChain（直接调用模型/链）

这就是你的技术层。但任务尚未完成：在后续步骤4中，你必须在编写任何Agent代码之前加载对应技术层的专属技能。

</decision-table>

Tool Profiles

工具概况

<langchain-profile>

LangChain — agent framework

LangChain — Agent框架

Best for:

Single-purpose agents with a fixed tool set
RAG pipelines and document Q&A
Model calls, prompt templates, structured output

Not ideal when:

The agent needs to plan across many steps or manage large context
Control flow is conditional, iterative, or parallel
State must persist across sessions

All LangChain agents use

create_agent(model, tools=[...])

</langchain-profile> <langgraph-profile>

最佳适用场景：

具有固定工具集的单一用途Agent
RAG管道与文档问答
模型调用、提示模板、结构化输出

不适用场景：

Agent需要跨多步规划或管理大上下文
控制流为条件型、迭代型或并行型
状态需要跨会话持久化

所有LangChain Agent均使用

create_agent(model, tools=[...])

。

</langchain-profile> <langgraph-profile>

LangGraph — agent runtime

LangGraph — Agent运行时

Best for:

Custom control flow — deterministic loops, reflection cycles, parallel fan-out
Complex workflows combining deterministic and agentic steps
Human-in-the-loop with precise interrupt and resume points
State that must survive failures or span long sessions

Not ideal when:

You want planning, file management, and subagent delegation out of the box (use Deep Agents instead)
The workflow is simple enough for a straight tool loop

All LangGraph graphs use

StateGraph(State)

with explicit nodes, edges, and conditional edges.

</langgraph-profile> <deep-agents-profile>

最佳适用场景：

自定义控制流——确定性循环、反思周期、并行分支
结合确定性步骤与Agent步骤的复杂工作流
具备精确中断和恢复点的人机协作流程
需在故障后保留或跨长会话存在的状态

不适用场景：

你需要开箱即用的规划、文件管理和子Agent委托功能（改用Deep Agents）
工作流足够简单，仅需常规工具循环即可完成

所有LangGraph图均使用

StateGraph(State)

，并包含显式节点、边缘和条件边缘。

</langgraph-profile> <deep-agents-profile>

Deep Agents — agent harness

Deep Agents — Agent工具集

Best for:

Long-running tasks that require planning and decomposition
Agents that read, write, and manage files across a session
Delegating subtasks to specialized subagents
Persistent memory across sessions
Loading domain-specific skills on demand

Not ideal when:

The task is simple enough for a single-purpose agent
You need precise hand-crafted control over every graph edge (use LangGraph directly)

All Deep Agents use

create_deep_agent(model, tools=[...])

</deep-agents-profile>

最佳适用场景：

需要规划与分解的长期运行任务
需在会话中读取、写入和管理文件的Agent
将子任务委托给专业子Agent的场景
跨会话的持久化记忆
按需加载特定领域技能

不适用场景：

任务足够简单，单一用途Agent即可完成
你需要对每个图边缘进行精确的手工控制（直接使用LangGraph）

所有Deep Agents均使用

create_deep_agent(model, tools=[...])

。

</deep-agents-profile>

Mixing Layers

混合技术层

<mixing-layers>

The tools are layered, so they can be combined in the same project. Common patterns:

Deep Agents orchestrator → LangGraph subagent — when the main agent needs planning and memory but one subtask requires a deterministic graph.
LangGraph graph wrapped as a tool or subagent — when a specialized pipeline (e.g. RAG, reflection loop) is called by a broader agent.

A compiled LangGraph graph can be registered as a named subagent inside Deep Agents — the orchestrator delegates to it via the

task

tool without knowing its internal structure. LangChain tools and retrievers work freely inside both LangGraph nodes and Deep Agents tools.

</mixing-layers>

<mixing-layers>

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

Deep Agents编排器 → LangGraph子Agent — 当主Agent需要规划和记忆，但某个子任务需要确定性图时。
LangGraph图包装为工具或子Agent — 当专业管道（如RAG、反思循环）被更上层的Agent调用时。

编译后的LangGraph图可在Deep Agents中注册为命名子Agent——编排器通过

task

工具向其委托任务，无需了解其内部结构。LangChain工具和检索器可在LangGraph节点和Deep Agents工具中自由使用。

</mixing-layers>

Step 2 — Set Environment Variables

步骤2 — 设置环境变量

Always set these for observability. These are the current LangSmith env var names. Copy them as-is. OLDER NAMES NO LONGER WORK.

<environment-variables> LANGSMITH_API_KEY=<your-key> LANGSMITH_TRACING=true LANGSMITH_PROJECT=<project-name> </environment-variables>

Model-provider and tool-specific keys (

ANTHROPIC_API_KEY

OPENAI_API_KEY

TAVILY_API_KEY

, etc.) depend on your stack — set them as needed.

为了实现可观测性，请务必设置以下变量。这些是当前LangSmith的环境变量名称，请原样复制。旧名称已不再生效。

<environment-variables> LANGSMITH_API_KEY=<your-key> LANGSMITH_TRACING=true LANGSMITH_PROJECT=<project-name> </environment-variables>

模型供应商和工具专属密钥（

ANTHROPIC_API_KEY

、

OPENAI_API_KEY

、

TAVILY_API_KEY

等）取决于你的技术栈——按需设置即可。

Step 3 — How the Docs Work

步骤3 — 文档使用指南

<docs>

All documentation lives at docs.langchain.com, organized into two top-level sections:

OSS — LangChain, LangGraph, Deep Agents. Python (
```
/oss/python/
```
) and TypeScript (
```
/oss/javascript/
```
) trees in parallel.
LangSmith — observability, evaluation, deployment, prompt engineering.

Each product has its own page tree: overview → quickstart → how-to guides → reference.

<docs>

所有文档均托管在 docs.langchain.com，分为两个顶级板块：

OSS — LangChain、LangGraph、Deep Agents。包含Python（
```
/oss/python/
```
）和TypeScript（
```
/oss/javascript/
```
）并行目录结构。
LangSmith — 可观测性、评估、部署、提示工程。

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

Canonical landing pages

标准起始页面

Start here rather than tree-searching from root (swap

python

→

javascript

for TypeScript):

LangChain —
```
/oss/python/langchain/overview
```
LangGraph —
```
/oss/python/langgraph/overview
```
Deep Agents —
```
/oss/python/deepagents/overview
```
LangSmith —
```
/langsmith/home
```
(no language split)

从以下页面开始，而非从根目录逐层搜索（TypeScript用户请将

python

替换为

javascript

）：

LangChain —
```
/oss/python/langchain/overview
```
LangGraph —
```
/oss/python/langgraph/overview
```
Deep Agents —
```
/oss/python/deepagents/overview
```
LangSmith —
```
/langsmith/home
```
（无语言分支）

Accessing docs in an agent context

在Agent场景中访问文档

If the LangChain Docs MCP server is connected (

mcp__docs-langchain__*

tools are available), query it directly:

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

If the MCP server is not available, use the

llms.txt

index:

Fetch
```
https://docs.langchain.com/llms.txt
```
— structured list of all pages with descriptions
Identify the 2–4 most relevant pages for the question
Fetch those pages directly for accurate, up-to-date content

Always prefer fetching live docs over relying on training-data knowledge — these libraries evolve fast and APIs change often.

</docs>

如果已连接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经常变更。

</docs>

Step 4 — Load the Right Skill Next

步骤4 — 加载对应的下一个技能

Now load the skill below that matches your layer from Step 1. This is required — the layer-specific skill carries the current API; the primer alone does not.

<next-skills>

现在加载与步骤1中所选技术层匹配的下方技能。这是必需的——技术层专属技能包含当前API；本入门指南本身不包含API内容。

<next-skills>

LangChain

langchain-fundamentals
— building any LangChain agent
langchain-rag
— adding RAG / vector store retrieval
langchain-middleware
— structured output with Pydantic
langchain-dependencies
— package versions, installs, or dependency management questions

langchain-fundamentals
— 构建任意LangChain Agent
langchain-rag
— 添加RAG/向量存储检索功能
langchain-middleware
— 使用Pydantic实现结构化输出
langchain-dependencies
— 包版本、安装或依赖管理相关问题

LangGraph

langgraph-fundamentals
— any LangGraph graph
langgraph-human-in-the-loop
— human-in-the-loop or approval workflows
langgraph-persistence
— state that must survive restarts, or cross-thread memory

langgraph-fundamentals
— 构建任意LangGraph图
langgraph-human-in-the-loop
— 人机协作或审批工作流
langgraph-persistence
— 需在重启后保留的状态，或跨线程记忆

Deep Agents

Always load
deep-agents-core
first. Then, as needed:

deep-agents-orchestration
— subagent delegation or orchestration
deep-agents-memory
— cross-session persistent memory

</next-skills>

请始终先加载
deep-agents-core
。然后根据需要加载：

deep-agents-orchestration
— 子Agent委托或编排
deep-agents-memory
— 跨会话持久化记忆

</next-skills>