把 LangChain 官方文档读透，比看一百篇 agent 科普文都管用

说 LangChain 被"过度抽象、调试困难"，是 2023 到 2024 年技术圈很主流的一个判断。那两年 GitHub Issue 和 Reddit 上骂声不少，甚至有"开发者为什么在放弃 LangChain"这种长帖。如果你对 LangChain 的印象还停在这里，可以先把这条印象搁置一下。

2025 年 10 月 22 日，LangChain 1.0 和 LangGraph 1.0 同一天正式发布。紧跟着，旧的python.langchain.com整站 308 永久重定向到新域名docs.langchain.com，传统意义上的"tutorials 目录页"消失了，文档结构彻底重写。

这件事比"一个框架发了 1.0"重要得多。

我的观点是：1.0 之后 LangChain 的官方文档，已经悄悄变成当下最系统的一份 agent 工程教科书。原因不是它写得多么文采飞扬，而是它做了一件别的科普文做不到的事——agent 工程每一次重大演进，都被直接刻进了它的 API 命名和页面结构里。读这份文档，等于在按 agent 工程的成熟度路线图，倒着走一遍。

下面把这份"教科书"拆开讲：它讲了哪些关键内容，分别适合谁掌握，用在哪些类型的 AI 产品里，怎么用。

这份教科书的"三句话总纲"

在进入具体章节前，先把这份文档的三句纲领性判断拎出来。这三句不在某一篇博客里，而是写在新版文档的 overview 和迁移指南里，是 1.0 之后所有内容的地基。

第一句定义：Agent = Model + Harness

新版 overview 开篇给出的 agent 定义不是"能自主完成任务的智能体"这种含糊说法，而是一个工程公式：Agent = Model + Harness。Model 是推理引擎，Harness 是脚手架——脚手架里装的是 prompt、tools、middleware，以及所有塑造 agent 行为的东西。

这句话的价值在于，它一上来就把"agent"从一个神秘概念拆成了两个可以分别工程的零件。后面所有章节，本质都是在教你"怎么造脚手架"。

第二句区分：Workflow 和 Agent 不一样

官方专门有一页workflows-agents，把这两个长期被混用的概念划了一道清楚的分界线，原话可以直接引用：

Workflows have predetermined code paths and are designed to operate in a certain order.

Agents are dynamic and define their own processes and tool usage.

翻译过来：Workflow 有预定的代码路径，按固定顺序执行；Agent 是动态的，自己决定流程和工具使用。分水岭只有一个——LLM 对流程的控制权有多大。

官方还顺手把 Workflow 拆成五种模式（Prompt Chaining、Parallelization、Routing、Orchestrator-Worker、Evaluator-Optimizer），并明确指出 LangGraph 是一个"既能跑 Workflow、又能跑 Agent、还能两者混用"的统一框架。这页文档的价值，比网上九成"Agent 和 Workflow 有什么区别"的回答都要权威。

第三句演进史：四条 API 演进线，每条都是 agent 工程的一次成熟

这是我觉得这份文档最有"教科书感"的地方。它没有保留旧 API 来兼容历史，而是直接把废弃写在了迁移指南里——废弃的时机和替代方案，本身就是 agent 工程演进的化石。挑四条最重要的：

读懂这四条线，就等于读懂了过去两年 agent 工程最关键的四个成熟节点。这也是为什么我说读官方文档比看科普文管用——科普文只会告诉你"现在流行 create_agent"，而官方文档会把"为什么 AgentExecutor 被淘汰、淘汰之后老代码怎么办、新 API 内部是怎么实现的"一并讲清楚。

六门核心课

新版文档不是按"教程列表"组织的，而是按"概念页"组织。下面挑六门最有教科书感的，按由浅入深的顺序拆。每门课讲清楚：它解决什么问题、核心 API、给谁、怎么用。

课一：模型调用（Chat Models）

这是最基础的一课，但别跳过——新版文档在这一课里埋了几个贯穿全篇的设计哲学。

它解决的问题是：用统一接口调用任何模型供应商（OpenAI、Anthropic、Google、Bedrock、阿里、智谱）。核心 API 是工厂函数init_chat_model("gpt-5.5")或直接ChatOpenAI()，统一方法invoke/stream/batch，统一消息类HumanMessage、AIMessage、SystemMessage、ToolMessage。

from langchain.chat_models import init_chat_model model = init_chat_model("gpt-5.5") response = model.invoke("为什么鹦鹉会说话？")

官方在文档里特别强调的几个细节，比代码本身更重要：网络错误、429 限流、5xx 错误会自动用指数退避重试，但 401/404 客户端错误不重试；流式输出的 chunk 被设计成"可累加成完整消息"；多模态通过统一的 content blocks 表达，跨供应商兼容。

给谁：第一次接触 LLM API 的开发者，以及需要在不同模型供应商之间切换的应用开发者。

课二：结构化输出（Structured Output）

这门课的分量，在 1.0 之后明显上升。它解决的问题是：让模型输出可预测、能直接被程序消费的结构化数据（Pydantic / dataclass / TypedDict / JSON Schema），不再靠正则去解析自然语言。

官方对它的新定位写得很直接——“今天大多数 LLM 原生支持结构化输出”。也就是说，旧版output_parsers那套"让模型吐 JSON 文本、再用解析器兜底"的方案，已经被模型原生的 tool-calling 能力取代了。

两条推荐路径：模型级用model.with_structured_output(Schema)；agent 级用create_agent(..., response_format=Schema)，结果从result["structured_response"]取。LangChain 会按模型能力自动选策略——支持原生结构化输出的走 ProviderStrategy（最可靠），不支持的回退到 ToolStrategy（用 tool calling 实现）。

from pydantic import BaseModel, Field from langchain.agents import create_agent class ContactInfo(BaseModel): name: str = Field(description="人名") email: str = Field(description="邮箱") agent = create_agent(model="gpt-5.5", response_format=ContactInfo) result = agent.invoke({"messages": [{"role": "user", "content": "张三，zhangsan@example.com"}]}) print(result["structured_response"]) # ContactInfo(name='张三', email='zhangsan@example.com')

给谁：所有要让模型驱动下游业务逻辑的开发者。只要你的 agent 不只是"陪聊"，而是要触发某个动作、写库、调 API，这门课就是必修的。

课三：工具调用（Tools）

工具是 agent 的"手脚"。这门课的核心 API 是@tool装饰器——把任意 Python 函数变成模型可调用的工具。

from langchain.tools import tool @tool def search_database(query: str, limit: int = 10) -> str: """在客户数据库里按关键词检索。 Args: query: 检索关键词 limit: 最多返回几条 """ return f"为 '{query}' 找到 {limit} 条记录"

这门课里有几个官方反复强调的硬规则，是真正值得记住的：类型注解是强制的，它们就是模型看到的工具入参 schema；工具名必须 snake_case，有些供应商会拒绝带空格或特殊字符的名字；config和runtime是保留参数名，自己不能用。

最巧妙的设计是ToolRuntime——这种参数对模型不可见，只用于在运行时给工具注入上下文（比如当前用户 ID、数据库连接）。它让工具能拿到运行时信息，又不会污染模型看到的工具签名。

给谁：所有要做 agent 的人。没有工具的 agent 只是聊天机器人。

课四：主入口 create_agent

这是 1.0 之后官方唯一推荐的 agent 写法，也是整份文档的核心。它解决的问题是：一行调用搭出"模型 + 工具循环 + 脚手架"的完整 agent。官方给它定位的原话是“a minimal, highly configurable harness”（一个最小化、高度可配置的脚手架）。

from langchain.agents import create_agent def get_weather(city: str) -> str: """查询指定城市的天气。""" return f"{city} 永远阳光明媚！" agent = create_agent( model="openai:gpt-5.5", tools=[get_weather], system_prompt="你是一个乐于助人的助手", ) result = agent.invoke( {"messages": [{"role": "user", "content": "旧金山天气怎么样？"}]} )

但create_agent真正的力量不在基础用法，而在它的middleware参数。1.0 把所有定制化能力都统一成了中间件——这是新架构最优雅的地方：

• ModelRetryMiddleware

  /ToolRetryMiddleware：容错

• PIIMiddleware

：护栏（比如自动脱敏邮箱）

• HumanInTheLoopMiddleware(interrupt_on={"write_file": True})

：人机回路

• SummarizationMiddleware

：自动压缩长对话

• SubAgentMiddleware

：子 agent 委派（配合 Deep Agents）

给谁：从原型走向生产的 agent 开发者。create_agent是默认起点，需要时再下钻到下一课的 LangGraph。

课五：LangGraph——需要可控时下钻

create_agent内部就是一张 LangGraph 图。当默认脚手架不够用时，下钻到 LangGraph 自己画图。这门课解决的问题是：做"确定性步骤 + LLM 步骤"混合的、可控、可持久化、可人机回路的 agent。

核心概念一组：StateGraph、节点（add_node）、边（add_edge）、条件边（add_conditional_edges）、State（TypedDict + reducer）、START/END、compile()、Command(goto=...)、interrupt()、checkpointer。

条件路由是这门课最关键的一块——它让 agent 能"按状态分支"。两种写法等价：

# 写法一：在边上声明路由 graph.add_conditional_edges("node_a", routing_function, {True: "node_b", False: "node_c"}) # 写法二：在节点内部用 Command 决定跳转 def my_node(state): if state["approved"]: return Command(update={"step": "done"}, goto="proceed") return Command(update={"step": "rejected"}, goto="cancel")

人机回路interrupt()是另一块硬骨头，文档给它列了五条硬规则，我觉得是整份文档里最"工程实战"的部分：不能用 try/except 包它（它是靠抛异常暂停的）；resume 值按严格索引匹配，调用顺序不能乱；只能传 JSON 可序列化的值；interrupt 之前的副作用在 resume 时会重新执行，所以必须幂等；静态断点interrupt_before不推荐用于人机回路，只用于调试。

记忆这块官方也讲清了边界：checkpointer 是短期、thread 内记忆，生产用PostgresSaver；store 是长期、跨 thread 记忆。老的ConversationBufferMemory那一票类全部废弃。

给谁：做企业级、长程、合规 agent 的架构师。当你的 agent 要落进受监管的行业（金融、医疗），或者要跑几个小时几天的长任务，就必须从create_agent下钻到这一层。

课六：LangSmith——把 agent 从原型推向生产

这门课经常被忽略，但它其实是 agent 从 demo 走到生产的关键一环。它解决两个问题：tracing（链路追踪）和 evaluation（评估）。

Tracing 的接入门槛低到反常：如果你用 LangChain 或 LangGraph，设一个环境变量LANGSMITH_TRACING=true，就自动全链路追踪，不用改一行代码。Replit 用它追踪跨多轮、几百步的 agent 执行流，还反过来推动了 LangSmith 在大规模 trace 摄取和渲染上的改进。

评估这块用的是 LLM-as-judge 这套做法：用client.evaluate(target, data=..., evaluators=[...])跑批量测试，判分函数用openevals包里预置的 prompt（如CORRECTNESS_PROMPT）。

给谁：所有要把 agent 上线的人。Replit、Elastic、LinkedIn、AppFolio、Uber——官方公开的标杆案例里，没有一家不上 LangSmith（或类似的可观测层）的。

还有两个值得点名的新东西，不展开讲：Deep Agents——面向长程任务的"全包"agent 框架，内置自动上下文压缩、托管长期记忆、调度；RAG 的做法也变了——从传统的"QA Chain"变成"Retrieve-Offload-Delegate"，检索到的 chunk 不再塞进 orchestrator 上下文，而是写进虚拟文件系统、委派子 agent 分析，并把检索内容"当数据不当指令"以防间接提示注入。

哪些 AI 产品该用 LangChain，哪些不该

工具的价值要在场景里看。下面把"该用"和"不该用"分开讲，每条都落到具体的产品类型和真实案例。

该用的四类场景

RAG 客服和文档问答。 这是最成熟的场景。组件齐全（loaders / splitters / embeddings / vectorstores / retrievers），LCEL 一条链就能跑通，1.0 之后又多了 Deep Agents 的 Retrieve-Offload-Delegate 这套新做法。这类产品对可控性要求中等、对上线速度要求高，是 LangChain 杠杆最大的场景。

研究助手和数据分析。 典型例子是 LinkedIn 的 SQL Bot——把自然语言转成 SQL 查询、自动纠错、处理找表和权限校验，是一个"基于 LangChain 和 LangGraph 的多 agent 系统"。Morningstar 的投资研究助手也属于这一类。这类产品的特点是流程有结构、但要留 LLM 的灵活判断空间。

行业 copilot 和工作流自动化。 AppFolio 的地产物业 copilot 是公开案例里数字最漂亮的——给物业经理每周节省超过 10 小时，能查信息、发消息、批量执行工单和账单。Rexera（地产工作流）、Vodafone（电信客服）、Definely（法律）都是同一类。这类产品往往需要可控的 agent 架构，实际多跑在 LangGraph 上。

长程、多 agent、需要人机回路的产品。 Replit Agent 是标杆——服务超过 3000 万开发者，trace 跨多轮、几百步，用多 agent 分工（规划、编辑、验证代码）加 human-in-the-loop。Elastic 的 AI Assistant 更值得讲：它是最早一批推出真正 AI agent 的公司，最初用 LangChain，后来整体迁到 LangGraph，原因是功能扩张后需要一个可控的 agent 架构。这个迁移案例本身就是"复杂 agent 该用哪一层"的答案。

不该用的三类场景

诚实地区分边界，比一味推荐更可信。

受监管行业的核心业务逻辑。 医疗、金融、物流这类行业要求可预测、可审计、fail predictably（出错要能预测地失败），而 LangChain 的隐式行为（静默重试、后台序列化、自动 prompt 格式化）会制造运行时意外。这类场景更稳妥的做法是直接用模型供应商的 SDK，自建显式的编排代码。

对成本高度敏感的应用。 框架会隐藏 prompt 和检索 chunk 的拼装细节，这是"沉默的预算杀手"——很难定位到底是检索拉了太多文本，还是 agent 在空转烧钱。对成本敏感的应用，自己控制每一次调用的输入输出更划算。

长期维护的核心业务能力。 这是 POC-to-production 的鸿沟问题。原型阶段 LangChain 是杠杆（works once 就行），但企业约束（数据驻留、可追溯、可审计）下来后会变成负担。官方案例都是大公司，但社区"过度抽象"的批评也持续存在，LangChain 1.0 据称就是在主动回应这些批评——不过这一点还需要时间验证。

判断标准可以简化成一句话：当你需要"快速搭一个能跑的 agent 原型"，用 LangChain；当你需要"一个能在生产里 fail predictably 的核心系统"，评估一下混用——在服务边界内借 LangChain 的组件（如 document loaders），核心业务逻辑用自有显式代码。

一条官方推荐的 agent 开发路径

把前面六门课串起来，就是一条从原型到生产的官方推荐路径。

第一步，起步。 用create_agent，五到十行代码出一个能调工具的 agent 原型。先别管 LangGraph，先让 agent 跑起来。

第二步，加观测。 开LANGSMITH_TRACING=true。这一步几乎零成本，但能让你看清 agent 每一步在干什么——调了哪个工具、传了什么参数、模型返回了什么。没观测就调 agent，等于闭眼开车。

第三步，要可控时下钻。 当默认脚手架不够用——比如要加条件分支、要并行、要在某个节点强制走确定性逻辑——下钻到 LangGraph，用StateGraph+add_conditional_edges自己画图。

第四步，要人审时加 interrupt。 当 agent 要执行高风险动作（写文件、发邮件、改库）时，用interrupt()或HumanInTheLoopMiddleware在动作前暂停，等人批准再恢复。注意前面讲的五条硬规则，尤其是幂等性。

第五步，要长程时上 Deep Agents。 当任务跨几小时、几天，agent 上下文会爆炸，就需要 Deep Agents 的自动上下文压缩和托管长期记忆。

第六步，要部署时用 LangGraph Platform。langgraph dev本地起服务、langgraph upDocker 起、langgraph build打镜像、langgraph deploy一键部署到 LangSmith Deployments，自带托管数据库做 checkpointing。

这条路径的关键不是每一步的具体命令，而是它的递进逻辑：先跑通，再观测，再可控，再人审，再长程，再部署。 跳步的人，要么原型跑不起来，要么生产挂得不明不白。

最后留一个问题，可以对照着想：你现在做的 agent，跑在官方推荐路径的哪一层？是停在 create_agent，已经下钻到 LangGraph，还是还在用 0.x 的 AgentExecutor？ 这个问题的答案，基本能预测你这个 agent 接下来半年的命运。

LangChain 这套文档并不完美——它依然有概念跨度大、新手不容易找到入口的问题。但它是目前唯一一份把 agent 工程从"调用一个模型"到"部署一个生产级多 agent 系统"完整讲清楚的官方资料。把它当教科书读，不是因为它权威，是因为它真实——真实地记录了一个 agent 框架两年里犯过的错、做过的一次次重写、最后收敛出来的工程共识。这种真实，比一百篇科普文都值钱。

想入门 AI 大模型却找不到清晰方向？备考大厂 AI 岗还在四处搜集零散资料？别再浪费时间啦！2026 年AI 大模型全套学习资料已整理完毕，从学习路线到面试真题，从工具教程到行业报告，一站式覆盖你的所有需求，现在全部免费分享！

👇👇扫码免费领取全部内容👇👇

​

一、学习必备：100+本大模型电子书+26 份行业报告 + 600+ 套技术PPT，帮你看透 AI 趋势

想了解大模型的行业动态、商业落地案例？大模型电子书？这份资料帮你站在 “行业高度” 学 AI：

1. 100+本大模型方向电子书

2. 26 份行业研究报告：覆盖多领域实践与趋势

报告包含阿里、DeepSeek 等权威机构发布的核心内容，涵盖：

• 职业趋势：《AI + 职业趋势报告》《中国 AI 人才粮仓模型解析》；
• 商业落地：《生成式 AI 商业落地白皮书》《AI Agent 应用落地技术白皮书》；
• 领域细分：《AGI 在金融领域的应用报告》《AI GC 实践案例集》；
• 行业监测：《2024 年中国大模型季度监测报告》《2025 年中国技术市场发展趋势》。

3. 600+套技术大会 PPT：听行业大咖讲实战

PPT 整理自 2024-2025 年热门技术大会，包含百度、腾讯、字节等企业的一线实践：

• 安全方向：《端侧大模型的安全建设》《大模型驱动安全升级（腾讯代码安全实践）》；
• 产品与创新：《大模型产品如何创新与创收》《AI 时代的新范式：构建 AI 产品》；
• 多模态与 Agent：《Step-Video 开源模型（视频生成进展）》《Agentic RAG 的现在与未来》；
• 工程落地：《从原型到生产：AgentOps 加速字节 AI 应用落地》《智能代码助手 CodeFuse 的架构设计》。

二、求职必看：大厂 AI 岗面试 “弹药库”，300 + 真题 + 107 道面经直接抱走

想冲字节、腾讯、阿里、蔚来等大厂 AI 岗？这份面试资料帮你提前 “押题”，拒绝临场慌！

1. 107 道大厂面经：覆盖 Prompt、RAG、大模型应用工程师等热门岗位

面经整理自 2021-2025 年真实面试场景，包含 TPlink、字节、腾讯、蔚来、虾皮、中兴、科大讯飞、京东等企业的高频考题，每道题都附带思路解析：

2. 102 道 AI 大模型真题：直击大模型核心考点

针对大模型专属考题，从概念到实践全面覆盖，帮你理清底层逻辑：

3. 97 道 LLMs 真题：聚焦大型语言模型高频问题

专门拆解 LLMs 的核心痛点与解决方案，比如让很多人头疼的 “复读机问题”：

三、路线必明： AI 大模型学习路线图，1 张图理清核心内容

刚接触 AI 大模型，不知道该从哪学起？这份「AI大模型 学习路线图」直接帮你划重点，不用再盲目摸索！

路线图涵盖 5 大核心板块，从基础到进阶层层递进：一步步带你从入门到进阶，从理论到实战。

L1阶段:启航篇丨极速破界AI新时代

L1阶段：了解大模型的基础知识，以及大模型在各个行业的应用和分析，学习理解大模型的核心原理、关键技术以及大模型应用场景。

L2阶段：攻坚篇丨RAG开发实战工坊

L2阶段：AI大模型RAG应用开发工程，主要学习RAG检索增强生成：包括Naive RAG、Advanced-RAG以及RAG性能评估，还有GraphRAG在内的多个RAG热门项目的分析。

L3阶段：跃迁篇丨Agent智能体架构设计

L3阶段：大模型Agent应用架构进阶实现，主要学习LangChain、 LIamaIndex框架，也会学习到AutoGPT、 MetaGPT等多Agent系统，打造Agent智能体。

L4阶段：精进篇丨模型微调与私有化部署

L4阶段：大模型的微调和私有化部署，更加深入的探讨Transformer架构，学习大模型的微调技术，利用DeepSpeed、Lamam Factory等工具快速进行模型微调，并通过Ollama、vLLM等推理部署框架，实现模型的快速部署。

L5阶段：专题集丨特训篇 【录播课】

四、资料领取：全套内容免费抱走，学 AI 不用再找第二份

不管你是 0 基础想入门 AI 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：

👇👇扫码免费领取全部内容👇👇

​

2026 年想抓住 AI 大模型的风口？别犹豫，这份免费资料就是你的 “起跑线”！