1. LangChain要解决什么问题 #
直接调大模型厂商的 HTTP API，也能做出「一问一答」。Demo 阶段够用：发一段 prompt，拿回一段文本。
真实业务很快会碰到另一类问题——不是「模型聪不聪明」，而是「系统怎么拼得住、怎么换得起、怎么查得清」：
- 要换模型（OpenAI → DeepSeek → 本地 Ollama），调用代码到处改
- 要让模型查天气、查数据库、调内部接口，手写「模型 ↔ 工具」循环又臭又长
- 要做企业知识库问答（RAG），文档加载、切分、向量化、检索、生成要串成流水线
- 要多轮对话、护栏、重试，以及危险操作先经人审核再执行
- 上线后不知道模型为什么答错，排障只能靠猜
这些痛点可以归成四类：
| 类别 | 典型表现 |
|---|---|
| 集成 | 换供应商、换嵌入模型、换向量库，业务代码跟着碎 |
| 编排 | 工具循环、分支、重试、人机协同，手写状态机易错 |
| 知识 | 私有文档进不了模型上下文，需要 RAG 流水线 |
| 可观测 | 不知道调了哪个工具、耗时多少、哪一步答歪了 |
LangChain 要做的，就是把这些能力拆成可组合的积木，再用统一的 Agent 驾驭层拼成可上线的应用。
本章先不写业务代码，只建立这张「地图」：定位、公式、产品族、Agent 循环、积木表、安装与学习路线。第一个 Agent 留到第 2 章再跑通。
2. LangChain 是什么 #
LangChain 的核心定位可以收成一句话：
Agent = Model + Harness（智能体 = 模型 + 驾驭层）
| 部分 | 含义 | 例子 |
|---|---|---|
| Model（模型） | 负责推理与决策 | 选不选工具、理解工具结果、给出最终回答 |
| Harness（驾驭层） | 围绕模型循环的一切 | 提示词、工具、塑造行为的 middleware（中间件） |
常见误解：LangChain 不只是「又一个调 API 的 SDK」。它还提供标准循环与可扩展的驾驭层——你不必每次从零手写「调模型 → 看要不要工具 → 执行 → 回灌 → 再调模型」。
入口是高度可配置的 create_agent：从一个最小驾驭层起步，再按需叠加能力。模型侧支持 OpenAI、Anthropic、Google 等大量供应商。
可以把它理解成：
你要做的应用
│
▼
create_agent（标准「模型 ↔ 工具」循环 + 可扩展中间件）
│
├── Model：openai / deepseek / anthropic / ollama …
├── Tools：查库、调 API、算数、检索知识库 …
├── Prompt：系统人设、业务约束
└── Middleware：护栏、重试、限流、人机协同 …记法建议：
- Model = 会思考、会选型的大脑
- Tools / Prompt / Middleware = 驾驭层里可插拔的部件
create_agent= 把它们装进标准循环的入口
本教程默认用 DeepSeek（deepseek:deepseek-v4-flash）；这套心智模型换其他供应商同样适用。
3. 为什么需要 LangChain #
§1 讲的是「痛」；本节换成「框架具体怎么帮你」。第一章不必背 API，先建立「为什么值得学」的预期。
| 痛点 | LangChain 怎么帮你 |
|---|---|
| 换模型要改一大堆调用代码 | 统一聊天模型 / 嵌入接口，供应商可切换 |
| 工具调用、多轮循环手写易错 | create_agent 提供标准「模型 ↔ 工具」循环 |
| 需要护栏、重试、路由、权限 | 用 middleware 渐进增强驾驭层 |
| 要可观测、评测、上线排错 | 与 LangSmith 深度集成 |
| 要持久化、人机协同、长任务 | Agent 构建在 LangGraph 之上 |
官方强调四大核心收益（见 Overview · Core benefits）：
- 标准模型接口 — 聊天模型、嵌入等跨供应商统一；换模型时业务代码改动最小。
- 高度可配置的驾驭层 — 从最小的
create_agent起步，用 middleware 按需加护栏、重试、路由、工具策略等。 - 构建在 LangGraph 之上 — 持久执行、人机协同（human-in-the-loop）、状态持久化等编排能力拿来即用。
- 用 LangSmith 调试 — 在一处查看轨迹、工具调用、状态迁移与延迟，定位失败模式并改进质量。
和「直接调厂商 SDK」比，LangChain 的价值不在「多包一层」，而在：
- 把 换模型 / 换工具 / 加护栏 变成改配置、插积木，而不是重写循环
- 把 调试 从 print 猜谜，升级成轨迹级可观测（LangSmith）
- 为后面的 RAG、图编排、生产护栏 留出同一套组合方式
4. LangChain产品族谱 #
LangChain 很少单独出场。名字相近的几个产品分工不同，混为一谈容易在选型时踩坑。
| 产品 | 角色 | 什么时候选 |
|---|---|---|
| Deep Agents | 「开箱即用」的 agent | 要规划、子 Agent、虚拟文件系统、上下文压缩等现成能力 |
LangChain（create_agent） |
可高度定制的 Agent 框架 | 要按业务精确组装模型 / 工具 / 提示 / 中间件 |
| LangGraph | 底层编排运行时 | 要在同一图里混合「确定性步骤 + 智能体步骤」 |
| LangSmith | 观测、评测与部署配套 | 追踪、调试、评估上述任一框架构建的 Agent |
选型直觉：
想要最快上手、功能齐 → Deep Agents
想要可控、可裁剪的 Agent → LangChain create_agent
想要图编排与生产级状态机 → LangGraph
想要看清每次调用发生了什么 → LangSmith关系可以记成：越往上开箱越省事，越往下可控性越强。
Deep Agents
↑ 建在之上
LangChain Agents（create_agent）
↑ 建在之上
LangGraph（图编排 / 持久化 / HITL）
↑ 搭配使用
LangSmith（追踪 / 评测 / 排障）本教程以 LangChain create_agent + 核心积木 为主线，后面会自然衔接到 RAG、LangGraph 与 LangSmith。
第 1～2 章先建立心智模型并跑通，不必一上来啃满整条产品线。Deep Agents 知道存在即可；本教程主路径是 create_agent。
5. Agent 怎么工作 #
官方定义（Agents）：
Agent 是一个在循环中不断调用工具、直到完成任务的模型。
驾驭层（Harness）是这个循环周围的一切：提示、工具、以及塑造模型行为的中间件。
驾驭层的职责：在正确的时间，给模型正确的上下文。
关键区别：
| 单独调模型 | Agent | |
|---|---|---|
| 典型输入 | 一段话 / 一组消息 | 用户目标 + 可用工具 |
| 过程 | 一次（或固定链）生成 | 可能多轮：推理 → 工具 → 再推理 |
| 结束条件 | 模型吐完文本 | 模型认为任务完成，给出最终回答 |
简化循环：
用户输入
↓
模型推理（要不要调工具？调哪个？参数是什么？）
↓
若需要 → 执行工具 → 把结果塞回消息 → 再推理
↓
否则 → 输出最终回答对应官方组件架构里的「Agent with tools」模式（见 Component architecture）：
User request → Agent → 需要工具? ──Yes→ Call tool → 结果回传 Agent
└─No→ Final answer读到这里，记住三句话即可：
- 模型决定要不要动手、动哪只手（工具）
- 驾驭层执行工具，并把结果写回对话状态
- 循环直到模型给出最终回答（或触发停止条件）
第 2 章会带你跑通一个天气助手，并打印完整消息轨迹；本章不必死记每一种消息类型。
6. LangChain核心积木 #
即便最终目标是 Agent，LangChain 仍由一组可组合积木构成。官方把它们分成几大类（Component architecture）。
先建立「目录感」：后面各章大多是把某一块积木拆开讲透。此刻不必抠实现，知道它干什么、大致何时用、对应哪一章即可。
| 类别 | 作用 | 典型用途 | 本教程章节 |
|---|---|---|---|
| Models | AI 推理与生成 | 聊天、结构化输出、嵌入 | 第 3 / 6 章 |
| Messages / Prompts | 对话状态与提示组织 | 多轮对话、模板化提示 | 第 4～5 章 |
| Tools | 外部能力 | 查库、调 API、计算、检索 | 第 8 章 |
| Agents | 编排与决策 | 工具循环、非确定性工作流 | 第 2 / 9 章 |
| Middleware | 横切增强 | 护栏、重试、HITL | 第 10 章 |
| Memory | 上下文保持 | 多轮对话、自定义状态 | 第 11 章 |
| Document processing | 数据摄入 | PDF / 网页加载与切分 | 第 12～13 章 |
| Embeddings / Vector Stores | 语义检索存储 | Chroma、FAISS、Pinecone 等 | 第 14 章 |
| Retrievers | 信息获取 | RAG、知识库搜索 | 第 15 章 |
| Long-term Memory / Store | 跨会话记忆 | 用户档案、偏好、长期事实 | 第 16 章 |
数据在应用里大致这样流动（尤其是 RAG 类应用）：
① 输入处理：加载文档 → 切分 → Documents
② 嵌入存储：Embedding → Vectors → Vector Store
③ 检索：用户问题 → 向量化 → Retriever → 相关上下文
④ 生成：Chat Model（± Tools）→ 回答
⑤ 编排：Agent + Memory 把以上环节串起来整体关系可以记成：
┌─────────────────────────────────────────────┐
│ create_agent │
│ model + tools + system_prompt + middleware │
└──────────────────────▲──────────────────────┘
│ 由积木拼装 / 扩展
messages · prompts · tools · runnable
loaders · splitters · embeddings · retrievers下面各小节只做「一句话定位」；细节进对应章节。
6.1. Model（模型） #
见 Models。模型是 Agent 的「大脑」，也可单独用（分类、抽取、生成）——不是所有任务都要上 Agent。第 3 章会系统讲 init_chat_model、参数与流式。
常见能力：
- Tool calling：调用外部工具并把结果纳入回答（第 8 章深入）
- Structured output：按约定 schema 输出 JSON / Pydantic 对象（第 6 章）
- Multimodality：图文等多模态（第 4 章入门）
- Streaming：流式输出，改善交互体验（第 2～3 章）
6.2. Messages（消息） #
见 Messages。消息是模型交互的基本状态单元：Agent 的「记忆快照」就是不断增长的 messages 列表。常见角色（第 4 章展开）：
| 类型 | 角色 | 含义 |
|---|---|---|
SystemMessage |
system | 人设与全局约束 |
HumanMessage |
user | 用户输入 |
AIMessage |
assistant | 模型输出（可含 tool_calls） |
ToolMessage |
tool | 工具执行结果回传给模型 |
调试口诀：先看完整 messages，再看最后一句回答。 第 2 章会用打印轨迹练这个习惯。
6.3. Tools（工具） #
把检索、数据库、HTTP、业务函数暴露给模型。Agent 循环里，模型是「大脑」，工具是「手脚」。
第 2 章先用最简函数工具；第 8 章讲 @tool、参数 schema 与错误处理。工具已跑在独立进程、或要同时给多个宿主用时，走第 17 章 MCP。多个专家要隔离上下文或按步骤交接时，走第 18 章 Multi-agent。
6.4. Middleware（中间件） #
在驾驭层上增量加能力：护栏、重试、限流、PII 脱敏、人机协同等——不必一上来就把所有生产能力塞进第一版 Agent。
详见 Middleware；第 10 章练习。
6.5. RAG 相关组件 #
文档加载 → 切分 → 嵌入 → 向量库 → 检索 →（可选压缩重排）→ 模型生成。
这是企业知识库问答的标准路径：让模型回答你的私有文档里的内容，而不是只靠参数记忆。对应第 12～15 章；前面 Agent 积木学完后，再拼这条流水线会轻松很多。
7. 安装与生态包 #
LangChain 生态按「主框架 + 厂商集成 + 社区扩展」拆包。安装时记住：
业务从
langchain起步；接具体厂商装对应集成包；需要社区数据源再加langchain-community。
7.1. 安装 LangChain #
需要 Python 3.10+（见 Install）。Windows 下可用 PowerShell：
pip install -U langchain python-dotenv
# 或
uv add langchain python-dotenv按供应商安装集成包，例如：
pip install -U langchain-deepseek # DeepSeek（本文默认）
pip install -U "langchain[openai]" # OpenAI（含常用依赖组合）
pip install -U langchain-openai # 仅 OpenAI 集成
pip install -U langchain-anthropic # Anthropic
pip install -U langchain-ollama # 本地 Ollama本教程默认路径：langchain + langchain-deepseek + python-dotenv。
完整列表见 Integrations · Providers。
7.2. 常见包怎么分工 #
| 包 | 作用 |
|---|---|
langchain |
主框架：Agent、init_chat_model、高层编排入口 |
langchain-core |
核心抽象：消息、Runnable、工具协议等 |
langchain-openai / langchain-anthropic / … |
各厂商模型与嵌入适配 |
langchain-community |
社区维护的加载器、检索器、部分集成 |
langchain-text-splitters |
文本切分 |
langchain-chroma 等 |
向量库集成 |
langgraph |
底层图编排（Agent 运行时可依赖） |
入门阶段你主要直接 import 的是 langchain 与某个厂商包；langchain-core 通常作为依赖被间接安装。做 RAG 时再按需加 splitters、chroma 等。
7.3. API Key 与观测 #
密钥放进 .env，用 python-dotenv 加载；不要把真实 key 写进仓库或文档。
建议尽早打开 LangSmith Tracing；进一步可用 LangSmith Engine 根据轨迹发现问题并给出修复建议。
.env 示例（请替换为你自己的密钥，勿提交真实 key）：
DEEPSEEK_API_KEY="sk-xxx"
OPENAI_API_BASE="https://api.deepseek.com"
OPENAI_API_KEY="sk-xxx"
LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY="lsv2_pt_xxx"
LANGSMITH_PROJECT="langchain"说明：
DEEPSEEK_API_KEY：本教程默认模型所需OPENAI_API_*：部分兼容 / 迁移场景会用到；没有对应用法可先不配LANGSMITH_*：打开后可在 LangSmith 控制台看到每次调用轨迹
8. 典型应用场景 #
学框架最好先想清「我最终要做哪类应用」。下表把常见场景映射到积木组合与章节，方便按需跳读（仍建议按路线走一遍打底）。
| 场景 | 常用组合 | 对应章节 |
|---|---|---|
| 带工具的助理 | create_agent + 自定义 tools |
第 2 / 8 / 9 章 |
| 结构化信息抽取 | 模型 + Structured Output | 第 6 章 |
| 多轮客服 / 会话 | 消息历史 + Agent / Memory | 第 4 / 11 章 |
| 知识库问答（RAG） | 加载 → 切分 → 嵌入 → 检索 → 生成 | 第 12～15 章 |
| 记住用户偏好 / 内部档案 | Store 长期记忆 + 记忆工具 |
第 16 章 |
| 复杂业务流程 | LangGraph：确定性节点 + Agent 节点 | 第 19 章起 |
| 生产排障与评测 | LangSmith 追踪 / 评测 | 第 29 章起 |
粗线条对应关系：
助理 / 办公自动化 → Agent + Tools（± Middleware）
单据 / 工单抽取 → Structured Output
企业文档问答 → RAG 全链路
审批 / 多步业务 → LangGraph
上线质量与排障 → LangSmith
9. 学习路线 #
本教程按「先跑通 → 拆积木 → 组 Agent → 做 RAG → 上线观测」推进。
第 1 章只要求建立地图；第 2 章马上动手。
第1章 总览 ← 你在这里
│
▼
第2章 第一个 Agent ──► 建立「跑通」信心
│
├─► 第3–5章 模型 / 消息 / 提示
├─► 第6–7章 结构化输出 / Runnable
├─► 第8–10章 工具 / Agent / Middleware（MCP 见第 17 章，多 Agent 见第 18 章）
├─► 第11章 会话记忆
├─► 第12–15章 RAG 全链路
├─► 第16章 长期记忆（跨会话）
└─► 第19章起 LangGraph / LangSmith / 综合项目阶段心智：
| 阶段 | 你在学什么 |
|---|---|
| 第 2 章 | 最小 Agent 闭环与消息轨迹 |
| 第 3～7 章 | 模型、消息、提示、结构化输出、组合链 |
| 第 8～11 章 | 工具、Agent 深入、护栏、记忆（外部 MCP 工具见第 17 章，多 Agent 见第 18 章） |
| 第 12～15 章 | 企业知识库（RAG）主线 |
| 第 16 章 | 长期记忆：跨会话的档案与偏好（用到第 14 章的向量检索，所以排在 RAG 之后） |
| 第 17 章 | MCP：把独立进程里的工具接到 Agent |
| 第 18 章 | Multi-agent：子 Agent / 交接 / Skills / Router |
| 第 19～28 章 | 图编排（LangGraph） |
| 第 29～38 章 | 观测与评测（LangSmith） |
| 第 39～52 章 | Deep Agents：官方攒好的整机（虚拟文件系统、Skills、子智能体、审批） |
| 第 53～62 章 | 综合实战项目 |
下一章： 打开第 2 章，把天气助手跑通，并学会阅读完整消息轨迹。
10. 文档 #
官方文档是「查细节」的主阵地；本章是「建地图」。遇到具体 API 行为不确定时，优先回官方页，再对照本教程章节。
11. 本教程章节与官方文档对照 #
官方 Overview 强调四块核心能力：统一模型接口、可配置的驾驭层、基于 LangGraph 的执行、LangSmith 观测。下表把本教程前 10 章与官方主题对齐，方便「查官方细节 ↔ 回本教程看例子」：
| 官方主题 | 官方链接 | 本教程章节 | 说明 |
|---|---|---|---|
| Overview / Quickstart | overview · quickstart | 第 1～2 章 | 定位、create_agent 最小闭环 |
| Models | models | 第 3 章 | init_chat_model、stream/batch/异步 |
| Messages | messages | 第 4 章 | 四类消息、工具环、多轮与 checkpoint 预览 |
| Prompts | prompts API 参考 | 第 5 章 | 模板、少样本、占位符（1.x 文档已无独立 Prompts 指南页，细节以 API 参考为准） |
| Structured output | structured-output | 第 6、9 章 | 模型层 + Agent 层 response_format |
| Runnable / LCEL | component-architecture | 第 7 章 | 组合链、流式与异步速查 |
| Tools | tools | 第 8 章 | @tool、schema、错误回灌 |
| MCP | mcp | 第 17 章 | langchain-mcp-adapters、stdio / HTTP、接到 Agent |
| Multi-agent | multi-agent | 第 18 章 | Subagents / Handoffs / Skills / Router |
| Agents | agents | 第 2、9 章 | 驾驭层参数与动态 middleware |
| Middleware | middleware | 第 9～10 章 | 自定义钩子 + 内置护栏 |
| Guardrails | guardrails | 第 10 章 | PII、限流、HITL 等生产护栏 |
| Short-term memory | short-term-memory | 第 4 预览 · 第 11 章 | checkpointer、thread_id |
| Long-term memory | long-term-memory | 第 16 章 | Store、命名空间、语义检索、记忆工具 |
| Streaming | streaming | 第 2、3、7 章 | 模型 / 链 / Agent 三层对照 |
| Runtime | runtime | 第 9 章 §5.1 · 第 19 章 | ModelRequest、context、store |
| LangGraph | langgraph | 第 19～28 章 | 状态与 reducer、条件边、循环、持久化、HITL 底层 |
| LangSmith | observability | 第 2 章 · 第 29～38 章 | Tracing、评测、排障 |
第 11 章之后补齐官方文档里同样重要、但前 10 章只预告过的内容：
| 章节 | 补齐的官方能力 | 状态 |
|---|---|---|
| 第 11 章 Memory | 短期记忆、checkpoint 持久化、上下文裁剪、自定义 state | 已完成 |
| 第 12～15 章 RAG | Document loaders、splitters、vector stores、混合检索与重排 | 已完成 |
| 第 16 章 长期记忆 | Store 读写、命名空间划分、语义检索、Agent 自主记忆 |
已完成 |
| 第 17 章 MCP | 外部 MCP 服务器 → LangChain 工具 → create_agent |
已完成 |
| 第 18 章 Multi-agent | Subagents / Handoffs / Skills / Router | 已完成 |
| 第 19～28 章 LangGraph | 图状态、条件边、循环、interrupt、astream_events |
已完成 |
| 第 29～38 章 LangSmith | 数据集评测、对比实验、线上监控、质量闭环 | 已完成 |
| 第 39～52 章 Deep Agents | 虚拟文件系统、权限沙箱、Skills、子智能体、审批、装配顺序 | 已完成 |
| 第 53～62 章 综合项目 | 企业知识库 + 护栏 + 记忆 + 观测端到端 | 待编写 |
查阅技巧：不确定 API 行为时，先用 llms.txt 搜页面标题，再回上表找对应本教程章节约读例子。