在 LangChain/LangGraph/Deep…

任何 LangChain / LangGraph / Deep Agents 智能体构建项目，都应先执行本技能，以确定用哪层工具、配置环境变量、查最新文档并加载正确的后续技能。

适用场景

解决思路

1. 对任何 LangChain / LangGraph / Deep Agents 智能体构建项目，先调用本 `ecosystem-primer` 技能，再咨询其他技能或编写任何 agent 代码；把它作为获取最新框架选择、agent 模式、安装、环境设置和下一步技能的唯一起点。
2. 按自上而下分层心智模型理解栈：Deep Agents 是顶层 harness，基于 LangChain + LangGraph，内置 planning、file management、subagent spawning、memory；LangGraph 是中层 runtime，用于 durable execution、custom control flow、stateful workflows，LangChain agents 运行在其上；LangChain 是底层 framework，提供 models、tools、agent loop 抽象，provider-agnostic 且最易起步；LangSmith 是横切 observability/evaluation 平台，framework-agnostic，建议始终搭配使用。
3. 理解高层依赖低层，但不必直接使用低层：Deep Agents 可让你不写 graph code 获得 LangGraph durable execution；LangChain 可让你不管理 graph edges 获得 models 和 tools。
4. 执行 Step 1 选型时，按顺序评估条件并在第一个匹配处停止：若任务需要 planning、跨长会话 file management、persistent memory、subagent delegation 或 on-demand skills → 选择 Deep Agents。
5. 否则，若任务需要 custom control flow（deterministic loops、branching logic）→ 选择 LangGraph。
6. 否则，若是 single-purpose agent 且工具集固定 → 选择 LangChain，使用 `create_agent` 函数。
7. 否则，若是 pure model call、retrieval pipeline 或 simple prompt chain 且没有 agent loop → 选择 LangChain，使用 direct model / chain。
8. 记录选出的层，但不要就此停止：到 Step 4 时必须先加载该层专属技能，然后才能编写任何 agent 代码。
9. 若选择 LangChain，按 profile 操作：适合 single-purpose agents with a fixed tool set、RAG pipelines and document Q&A、model calls、prompt templates、structured output；所有 LangChain agents 使用 `create_agent(model, tools=[...])`。
10. 若选择 LangGraph，按 profile 操作：适合 custom control flow（deterministic loops、reflection cycles、parallel fan-out）、复杂 workflows 混合 deterministic 与 agentic steps、human-in-the-loop with precise interrupt and resume points、必须跨故障或跨长会话存活的状态；所有 LangGraph graphs 使用 `StateGraph(State)` 并配显式 nodes、edges、conditional edges。
11. 若选择 Deep Agents，按 profile 操作：适合 long-running tasks requiring planning and decomposition、跨会话读写和管理文件的 agents、把子任务委派给 specialized subagents、跨会话 persistent memory、按需加载 domain-specific skills；所有 Deep Agents 使用 `create_deep_agent(model, tools=[...])`。
12. 混合层使用时，采用常见模式：Deep Agents orchestrator → LangGraph subagent，用于主 agent 需要 planning 和 memory、但某个子任务需要 deterministic graph 的场景。
13. 混合层使用时，采用常见模式：将 LangGraph graph 包装为 tool 或 subagent，用于 broader agent 调用 specialized pipeline（如 RAG、reflection loop）的场景。
14. 将编译后的 LangGraph graph 注册为 Deep Agents 内的 named subagent；orchestrator 通过 `task` 工具委派，不需要知道其内部结构。
15. 在 LangGraph nodes 和 Deep Agents tools 内自由使用 LangChain tools and retrievers。
16. 执行 Step 2：始终设置以下 LangSmith 环境变量用于 observability；使用当前 LangSmith env var 名称，原样复制，旧名称不再可用：`LANGSMITH_API_KEY=<your-key>`、`LANGSMITH_TRACING=true`、`LANGSMITH_PROJECT=<project-name>`。
17. 按栈需要设置 model-provider 和 tool-specific keys，例如 `ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`TAVILY_API_KEY` 等。
18. 执行 Step 3：所有文档位于 `docs.langchain.com`，按两个顶层部分组织：OSS（LangChain、LangGraph、Deep Agents，Python `/oss/python/` 与 TypeScript `/oss/javascript/` 树并行）和 LangSmith（observability、evaluation、deployment、prompt engineering）；每个产品有自己的 page tree：overview → quickstart → how-to guides → reference。
19. 查文档时从 canonical landing pages 开始，不要从 root 逐树搜索；TypeScript 时将 `python` 换成 `javascript`：LangChain `/oss/python/langchain/overview`、LangGraph `/oss/python/langgraph/overview`、Deep Agents `/oss/python/deepagents/overview`、LangSmith `/langsmith/home`（无语言拆分）。
20. 在 agent 上下文中查文档：若 LangChain Docs MCP server 已连接（`mcp__docs-langchain__*` tools 可用），直接查询 MCP。
21. 使用 MCP 时执行示例命令：`tree /oss/python -L 2` 探索 Python 结构；`tree /oss/javascript -L 2` 探索并行 TypeScript 结构；`cat /oss/python/langchain/quickstart.mdx` 读取指定页面；`rg -il "checkpointer" /oss/python/langgraph/` 按关键词搜索。
22. 若 MCP server 不可用，使用 `llms.txt` 索引：先抓取 `https://docs.langchain.com/llms.txt` 获取所有页面及描述的结构化列表。
23. 然后从中识别与问题最相关的 2–4 个页面。
24. 直接抓取这些页面，以获得准确、最新的内容。
25. 始终优先抓取实时文档，而不是依赖训练数据知识，因为这些库演进快、API 经常变化。
26. 执行 Step 4：若用户只想得到一个最小的本地可运行 agent（新项目、stub tool、provider key），先加载匹配的 quickstart：LangChain → `langchain-python-quickstart` 或 `langchain-typescript-quickstart`；LangGraph → `langgraph-python-quickstart` 或 `langgraph-typescript-quickstart`；Deep Agents → `deepagents-python-quickstart` 或 `deepagents-typescript-quickstart`。
27. 否则，加载 Step 1 所选层对应的技能；这是必需的，因为层专属技能包含当前 API，单靠 primer 不够。
28. 若层为 LangChain，加载：`langchain-fundamentals`（构建任何 LangChain agent）、`langchain-rag`（添加 RAG / vector store retrieval）、`langchain-middleware`（使用 Pydantic 做 structured output）、`langchain-dependencies`（包版本、安装或依赖管理问题）。
29. 若层为 LangGraph，加载：`langgraph-fundamentals`（任何 LangGraph graph）、`langgraph-human-in-the-loop`（human-in-the-loop 或 approval workflows）、`langgraph-persistence`（必须跨重启存活的状态或 cross-thread memory）。
30. 若层为 Deep Agents，始终先加载 `deep-agents-core`；然后按需加载 `deep-agents-orchestration`（subagent delegation 或 orchestration）、`deep-agents-memory`（跨会话 persistent memory）。

适用边界 · 注意事项

• 不适用于不使用 LangChain / LangGraph / Deep Agents 构建智能体的项目，或与 LangChain 生态无关的任务。
• 若只是纯模型调用、检索管线或简单提示链且已确定不需要 agent loop，可按具体 LangChain 文档/技能直接操作，不必用本 primer 做选型。
• 若已明确目标层级且只需要某个具体 API 细节，不应停留在 primer；应加载对应层技能或抓取实时文档。