LangChain 生态的新人十有八九被同一件事绕晕过：LangChain、LangGraph、Deep Agents 到底什么关系？是三个并列框架，还是学习曲线上的三站？官方文档一会儿说"框架"一会儿说"运行时"，越看越糊涂。症结在于官方按产品分了三类，依赖关系上却是四层——少算的那一层，正是所有困惑的来源。
三类产品，四层依赖
官方口径把生态分成三类：Runtime（LangGraph）、Framework（LangChain）、Harness（Deep Agents SDK）。产品确实是三个，但 LangChain 本身不是一个整块——它被 LangGraph 从中间劈成了两半：
langchain-core（积木：messages / tools / models / bind_tools）
↑ 依赖
LangGraph（运行时：图、状态、Checkpoint、流式）
↑ 依赖
create_agent + middleware（薄壳：LangChain 的另一半）
↑ 依赖
deepagents（套件：内置中间件栈）
langchain-core 在 LangGraph 之下，是它的地基；create_agent 在 LangGraph 之上，是包在外面的封装。把 LangChain 画成一整块叠在 LangGraph 上，讲 create_agent 时逻辑必然对不上——它明明包着 LangGraph，怎么会和垫在下面的 core 是同一个东西。
四层各自管什么
积木层提供最小原子：消息对象、工具声明、统一的模型调用接口、把工具绑上模型的 bind_tools。它不关心 Agent 怎么循环，只关心"一次调用怎么发"。
运行时层是执行引擎：图和边决定执行流，显式状态对象承载每一步的输入输出，检查点支持断点恢复，人在环接口支持任意节点暂停等确认。
薄壳层是省事封装：create_agent 工厂一行生成标准的"模型加工具"循环图，中间件栈提供模型调用前后、工具调用时机上的插入点。"薄"是刻意的——它不改变运行时语义，要精细控制随时下沉回 LangGraph。
套件层最省力：把写计划、读写文件、执行代码、长期记忆、人在环这些生产 Agent 几乎都要的能力预先打包。四层的关系一句话：每往上一层就是一层封装，每往下一层就是一层控制力。
一个真实报错的定位演示
AttributeError: 'BaseChatModel' object has no attribute 'bind_tools'
往 LangGraph 节点里传模型时最常见这个错。按依赖图定位：bind_tools 挂在模型对象上，属于积木层——报错几乎总是你传进去的不是 ChatModel 对象，可能是拿成了裸 provider 模型、废弃的旧基类，或者对象被错误包装过。顺着第一层去查模型对象本身，而不是在图逻辑里瞎翻。
排查时先跑版本自检，这类错误一大半源于版本错配：
pip show langchain langchain-core langgraph | grep -E "Name|Version"
pip check
四个包的版本要落在官方兼容矩阵内。特别是 LangChain 1.0 之后包结构大改：create_agent 升级为主入口，老的 legacy 链式组件整体挪进了独立的 langchain-classic 包，旧教程里 from langchain.chains import ... 的写法在 1.x 下会直接 ImportError——不是装错了，是搬走了。迁移到 1.x 时对照官方迁移指南逐项改 import，比重装环境快得多。
选型：从哪层下手
给四个真实场景对号入座：
- 明天要演示一个能调工具、带记忆、能写文件的 Agent → 套件层，一行代码的事，别手写状态图；
- 每次调模型前要按用户等级动态注入系统提示 → 薄壳层，
before_model中间件就是干这个的； - 多智能体编排，各自独立检查点、能回放任一步 → 运行时层，子图加检查点的地盘，套件层硬套会拧巴；
- 任何报错先问一句"这属于哪一层"——依赖图就是排查地图。
口诀两句话：能用高层绝不手写底层；要精确控制某一步，就下沉到管那一步的那层。学习顺序则反过来，从底层往上理解，从高层往下使用——理解时知道每个封装省掉了什么，使用时知道每个封装藏掉了什么，两头都通才算真正掌握这套生态。
评论0