LangChain Python：定位、安装与架构总览

/oss/python/langchain 是本 overview 的规范入口别名，浏览器最终落到 /overview。

一句话结论

LangChain 1.x 的核心不是“很多 Chain”，而是一个建立在 LangGraph 之上的、可组合的 agent harness：

Agent = Model + Harness

模型负责推理；harness 负责把正确的提示词、消息、工具、状态和中间件在正确时机交给模型。Python 的主要入口是 create_agent。需要预装规划、文件系统、上下文压缩和子代理时选 Deep Agents；需要显式图、确定性分支和底层状态控制时下沉到 LangGraph。

选择层级

层级	适合场景	默认代价
Deep Agents	长任务、研究、编码，希望直接获得完整 harness	约定更多，需理解其默认中间件与权限边界
LangChain `create_agent`	自己组合模型、工具、提示词、中间件，保持较高控制力	需要自行选择并配置生产能力
LangGraph	确定性流程、复杂状态机、持久恢复、自定义编排	抽象更低，开发与测试成本更高

三个层级不是互斥技术栈：Deep Agents 以 LangChain/LangGraph 能力组装完整 harness，LangChain agent 本身也是已编译的 LangGraph 图。

安装与最小路径

langchain 要求 Python 3.10+；可用 pip install -U langchain 或 uv add langchain。
模型、向量库和其他集成大多拆成独立 provider 包；例如通过 langchain[openai] 安装对应模型集成。核心包不会自动带上所有生态依赖。
凭证应由环境或密钥管理服务注入，不能硬编码、提交到仓库或写入笔记。
最小调用链：定义窄而清晰的工具函数 → create_agent(model=..., tools=..., system_prompt=...) → 以 messages 调用 invoke/ainvoke → 从最终 state 读取消息或结构化结果。
Quickstart 同时安装 langchain 与 deepagents，是为了展示从基础 agent 到完整 harness 的渐进路线，并不表示普通 LangChain agent 必须依赖 deepagents。

架构心智模型

LangChain 组件从数据到执行大致分五层：

输入处理：document loader 把外部数据转成 Document，splitter 切成可检索片段。
表示与存储：embedding 把文本向量化，vector store 建立相似度索引。
检索：retriever 根据查询返回相关文档。
生成与行动：model 生成内容；tool 把数据库、API、代码执行等能力交给模型选择。
编排与状态：agent 循环协调模型和工具；checkpointer、store、middleware 管理状态、记忆、可靠性与安全策略。

这套组件支持三类常见结构：固定的 2-step RAG、模型自行决定是否调用工具的 agent，以及 supervisor 协调 specialist 的多代理系统。先从单 agent 开始；只有上下文隔离、并行或组织边界确有收益时才增加多代理。

设计哲学与版本边界

LangChain 的两条长期主线是：

用统一的模型、消息和内容块接口减少 provider 锁定；
让模型不仅生成文本，还能通过工具编排外部数据与计算。

关键演进：早期以预定义 chains 为中心；随后从 ReAct/JSON 工具调用过渡到 provider 原生 function calling；LangGraph 补齐持久执行、流式、记忆和 HITL；LangChain v1.0 最终收敛到一个高层 agent 抽象，并标准化 reasoning、citation、server-side tool 等复杂内容块。旧 chains/agents 若暂不迁移，可由 langchain-classic 承载，但新代码不应继续扩大 classic 依赖面。

从基础 agent 组装 Deep Agent

“Build a data analysis agent from scratch” 展示了一个重要方法：不要把 Deep Agent 当黑盒，可以从 create_agent 逐层加入：

FilesystemMiddleware + sandbox backend：隔离文件和代码执行；
SummarizationMiddleware：在上下文过长前压缩旧消息；
SkillsMiddleware：按需加载领域知识；
TodoListMiddleware + SubAgentMiddleware：规划任务并把可隔离工作委派给子代理。

这样得到的基础与 create_deep_agent 相同，但每一层都可以替换或省略。生产上应优先明确 sandbox、文件持久性、出网权限和工具审批，而不是只验证模型能否跑通示例。

逐页覆盖索引

页面	学习结论
Overview	`create_agent` 是最小可配置 harness；LangChain 统一模型接口并复用 LangGraph 的持久化与 HITL。
Install	核心包要求 Python 3.10+；provider integrations 独立安装。
Quickstart	从安装、模型凭证、工具、基础 agent、真实场景到 LangSmith trace 的完整最短路径。
Philosophy	目标是降低 agent 起步成本、保持模型可替换，并把生产可靠性作为核心问题。
Component architecture	明确 loader、splitter、embedding、vector store、retriever、model、tool、agent、memory 的连接关系。
Deep agent from scratch	用中间件逐层装配 sandbox、压缩、skills、todos 和 subagents，说明 Deep Agents 并非另一套运行时。
Academy	该 docs URL 当前重定向到 LangChain Academy/Thinkific 课程首页；可见的是课程入口（Deep Agents 入门、LangSmith Essentials、Deployment 等），不是可逐章读取的公开 Markdown 教材。

实践检查清单

○ 新项目确认 Python 版本和每个 provider 包版本，不依赖隐式传递依赖。
○ 先用单 agent 与少量高质量工具验证任务闭环。
○ 需要持久状态时显式选择 checkpointer/store，不把进程内内存当生产存储。
○ 有副作用的工具在 schema、权限、HITL 和审计上同时设防。
○ 用真实 trace、集成测试与 eval 验证可靠性，不以一次 demo 成功代替生产结论。