把 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 工程演进的化石。挑四条最重要的旧 API已废弃新 API1.0 推荐这次演进意味着什么ConversationBufferMemory等一票 Memory 类LangGraph 的 state checkpointer记忆从框架黑盒变成可持久化、可回放、可按 thread 区分会话的状态对象AgentExecutor、initialize_agentlangchain.agents.create_agentAgent 不再是框架内部循环而是一张可下钻、可改造的 LangGraph 图output_parsers正则解析文本with_structured_output()/response_format结构化输出从靠提示词骗模型 解析文本变成模型原生能力LangServe2024-11-18 废弃LangGraph Platform langgraph dev/up/build/deploy部署从把 chain 包成 HTTP 服务变成把 agent 包成带托管数据库、支持 checkpointing 的 Agent Server读懂这四条线就等于读懂了过去两年 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_formatSchema)结果从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(modelgpt-5.5, response_formatContactInfo) result agent.invoke({messages: [{role: user, content: 张三zhangsanexample.com}]}) print(result[structured_response]) # ContactInfo(name张三, emailzhangsanexample.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( modelopenai: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、StateTypedDict 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}, gotoproceed) return Command(update{step: rejected}, gotocancel)人机回路interrupt()是另一块硬骨头文档给它列了五条硬规则我觉得是整份文档里最工程实战的部分不能用 try/except 包它它是靠抛异常暂停的resume 值按严格索引匹配调用顺序不能乱只能传 JSON 可序列化的值interrupt 之前的副作用在 resume 时会重新执行所以必须幂等静态断点interrupt_before不推荐用于人机回路只用于调试。记忆这块官方也讲清了边界checkpointer 是短期、thread 内记忆生产用PostgresSaverstore 是长期、跨 thread 记忆。老的ConversationBufferMemory那一票类全部废弃。给谁做企业级、长程、合规 agent 的架构师。当你的 agent 要落进受监管的行业金融、医疗或者要跑几个小时几天的长任务就必须从create_agent下钻到这一层。课六LangSmith——把 agent 从原型推向生产这门课经常被忽略但它其实是 agent 从 demo 走到生产的关键一环。它解决两个问题tracing链路追踪和 evaluation评估。Tracing 的接入门槛低到反常如果你用 LangChain 或 LangGraph设一个环境变量LANGSMITH_TRACINGtrue就自动全链路追踪不用改一行代码。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 / retrieversLCEL 一条链就能跑通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_TRACINGtrue。这一步几乎零成本但能让你看清 agent 每一步在干什么——调了哪个工具、传了什么参数、模型返回了什么。没观测就调 agent等于闭眼开车。第三步要可控时下钻。 当默认脚手架不够用——比如要加条件分支、要并行、要在某个节点强制走确定性逻辑——下钻到 LangGraph用StateGraphadd_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 趋势想了解大模型的行业动态、商业落地案例大模型电子书这份资料帮你站在 “行业高度” 学 AI1. 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 大模型的风口别犹豫这份免费资料就是你的 “起跑线”