---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - python
  - agents
  - architecture
topic: LangChain Python 定位、安装与架构总览
sources:
  - https://docs.langchain.com/oss/python/langchain
  - https://docs.langchain.com/oss/python/langchain/academy.md
  - https://docs.langchain.com/oss/python/langchain/component-architecture.md
  - https://docs.langchain.com/oss/python/langchain/deep-agent-from-scratch.md
  - https://docs.langchain.com/oss/python/langchain/install.md
  - https://docs.langchain.com/oss/python/langchain/overview.md
  - https://docs.langchain.com/oss/python/langchain/philosophy.md
  - https://docs.langchain.com/oss/python/langchain/quickstart.md
last_verified: 2026-08-11
---
# 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 组件从数据到执行大致分五层：

1. **输入处理**：document loader 把外部数据转成 `Document`，splitter 切成可检索片段。
2. **表示与存储**：embedding 把文本向量化，vector store 建立相似度索引。
3. **检索**：retriever 根据查询返回相关文档。
4. **生成与行动**：model 生成内容；tool 把数据库、API、代码执行等能力交给模型选择。
5. **编排与状态**：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 成功代替生产结论。

## 延伸

- [[02-Agent-Core-Primitives]]
- [[04-Middleware-Context-and-Runtime]]
- [[07-Production-Testing-and-Migration]]