LangChain 本身不是模型也不需要你从零搭一套算法框架它更像是一套把大模型能力组装进真实业务流的编排工具。做 Agent 应用时真正卡人的通常不是“模型答不对”而是“模型怎么按用户需求调用工具、记住上下文、返回结构化结果”。这套能力正是 LangChain 和 LangGraph 这类框架处理的重点。这篇内容适合刚接触 LangChain、想从 Model 调用一路做到 Agent 落地项目的开发者。重点不是把文档翻一遍而是先走通一条最小可运行的完整链路配置模型、定义工具、跑起一个带记忆和路由判断的 Agent最后再看常见报错怎么排查。标题里的 2026 更多是一个规划视角。底层依赖和模型能力变化非常快你在网上看到的写法可能几个月后就换了接口名所以落地时要以当前官方文档为准。下面我按照自己实际踩过坑之后的顺序把 LangChain 的 Model 调用、Agent 原理、完整项目实战和排错思路都拆开讲。1. 先搞清楚LangChain 解决什么问题1.1 不要把 LangChain 当成模型本身很多新手会误以为 LangChain 是某个大模型或者以为装了它就能离线跑出 GPT 效果。不是这样。LangChain 负责的是“整合”这一层它把大模型 API、提示词模板、输出解析、向量检索、工具调用、记忆存储这些零散能力串在一起。你可以把 LangChain 理解成一个乐高底座模型反而只是其中一个积木块。它解决的核心问题是当一个业务需要多种模型能力协作或者需要模型去调用外部工具、读取历史记忆、产出固定格式结果时你不需要为每一环手写一套胶水代码。我遇到过不少朋友直接拿 HTTP 库调一次模型接口觉得很简单然后问“那我为什么要用 LangChain”。答案取决于你要做什么。如果只是单次问答直接调 API 足够。但一旦需求变成先判断用户意图再决定查数据库还是查文件然后把结果交给模型总结最后按模板写报告手动拼装这套流程会让你很快崩溃。1.2 LangChain、LangGraph、Agent 框架之间的关系LangChain 是基础组件库提供模型封装、提示词、输出解析、工具协议、记忆接口。LangGraph 是建立在 LangChain 组件之上的“图状态编排”框架用节点和边描述流程能在节点之间传递状态、做条件分支、循环和人工介入。在社区里经常看到“LangChain 过时了吗”“langchain 和 langgraph 的区别”这类问题。更准确的说法是LangChain 官方把重心转向了 LangGraph尤其是复杂 Agent 项目基本都用 LangGraph 组织流程但 LangChain 的组件概念并没有消失。你依然需要用ChatOpenAI封装模型用tool定义工具用langchain-core里的基类管理消息和回调。所以入门时先学 LangChain 概念是合理的只是不要把“入门顺序”和“生产选型”搞混。有人还会把 LangChain 和 vLLM、PyTorch 放在一起比较。这其实不是一个维度。PyTorch 是深度学习框架vLLM 是高吞吐推理服务LangChain 则是应用层编排工具。你可以用 PyTorch 训练模型、用 vLLM 部署模型、用 LangChain 调用部署好的接口它们并不互斥。1.3 什么时候可以不用 LangChain只做一次性 Prompt 测试、只调一个模型接口、没有多步流程或工具调用需求这种情况下直接用官方 SDK 更轻量。引入 LangChain 不是为了炫技而是为了后续扩展。我建议的判断标准是需求只有“输入一段文本输出一段文本”不用 LangChain直接写 HTTP 调用。需求有“固定 Prompt 固定格式”先考虑函数封装再看提示词模板。需求有工具调用、多轮记忆、多路径判断、批量任务可以引入 LangChain再根据流程复杂度决定要不要上 LangGraph。2. 跑通第一个模型调用2.1 准备环境Python 版本、依赖安装、密钥配置我建议先建一个干净的虚拟环境不要直接装进系统 Python。常见组合是 Python 3.10 或 3.11这两个版本对很多依赖比较友好。3.12、3.13 能用但某些第三方包可能还没跟上遇到编译报错时先检查版本兼容性。安装依赖时按最常用的一套来pip install langchain langchain-core langchain-openai langchain-community如果后面要跑 Agent 和流程编排再加上 LangGraphpip install langgraph密钥配置有两种方式写环境变量或者写.env文件。我更推荐.env因为可以直接放在项目根目录用python-dotenv读取pip install python-dotenv在.env里写成OPENAI_API_KEY你的密钥 OPENAI_API_BASEhttps://api.example.com/v1关键提醒.env文件不要提交到 Git 仓库。我们踩过太多次密钥泄露的问题尤其是复制项目到 GitHub 时.env会直接出现在公开仓库里。一开始就在.gitignore里加一行.env是最省事的做法。2.2 最小模型调用代码与参数解释下面是一段最常见的 LangChain 模型调用代码按当前主流的 langchain-openai 包写法import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() llm ChatOpenAI( modeldeepseek-chat, api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_API_BASE), temperature0.2, timeout60, max_retries2, ) response llm.invoke(用一句话解释 Agent 是什么) print(response.content)注意base_url要带/v1这是 OpenAI 兼容接口的通用路径格式。如果你用的是 DeepSeek、Qwen、Moonshot 或者其他提供 OpenAI 兼容接口的服务商都可以通过这种方式接进来不需要改太多代码。几个参数的作用temperature控制随机性。0 到 1 之间偏向稳定输出就设在 0 到 0.3需要创意内容再调高。timeout请求超时时间。模型接口偶尔会慢不设超时任务可能一直挂着。max_retries失败重试次数。网络抖动时能自动重试但要注意如果是 400 这种参数错误重试没有意义。跑完以后response.content就是模型返回的文本。response本身是一个 AIMessage 对象里面除了内容还有usage_metadata、id、response_metadata等字段。排查问题时这些字段很有用比如看 token 消耗。2.3 兼容 DeepSeek 等模型的通用方式国内开发者经常用 DeepSeek 等模型很多人的第一反应是找“LangChain 接入 DeepSeek 专用包”。其实不用只要服务商提供 OpenAI 兼容接口直接用ChatOpenAI就可以。关键是三个信息要和模型服务商后台一致模型名比如deepseek-chat服务商支持哪个就填哪个。API 密钥权限、余额、白名单都会影响请求是否成功。接口地址一般形如https://api.example.com/v1填错会出现 404 或 401。我一般会先写一个单独的test_llm.py文件只做一次简单调用确认密钥、模型名和网络链路都通再继续开发后续功能。不要一上来就在 Agent 里排查模型调用问题那会把问题混在一起很难定位。如果你需要模型返回固定结构比如 JSON可以用with_structured_output配合 Pydantic 模型from pydantic import BaseModel class Answer(BaseModel): summary: str confidence: float structured_llm llm.with_structured_output(Answer) result structured_llm.invoke(总结一下什么是 Agent) print(result.summary, result.confidence)这种方式比自己在 Prompt 里写“请返回 JSON”稳定很多尤其适合后面做 Agent 工具结果解析。3. 理解 Agent 的核心链路模型、工具、记忆3.1 Agent 和普通链路的区别普通链路是“输入 - Prompt - 模型 - 输出”一次完成。Agent 不一样它让模型自主决定要不要调用工具、调用哪个工具、调用完再看结果继续回答。举个例子。用户问“查询一下上个月销售额最高的三个产品并生成一份分析报告”。模型本身没有数据它必须先调用一个查询工具拿到数据再调用报告生成工具最后给用户一个汇总。这个过程不是一次模型调用就能完成的而是一个循环模型根据用户输入决定调用某个工具并生成工具参数。程序执行该工具把结果返回给模型。模型观察工具结果判断下一步是继续调用工具还是直接回答。这就是 ReAct 循环的核心思路Reason推理和 Act行动交替进行。LangChain 里的create_react_agent就是这种模式的封装。理解了这个循环你才能真正明白 Agent 报错时问题出在哪个环节。3.2 工具定义与返回格式为什么关键在 LangChain 中定义一个工具很简单用tool装饰器from langchain_core.tools import tool tool def get_sales_stats(start_date: str, end_date: str) - str: 获取指定日期区间的销售统计返回可读文本。 # 实际场景中这里会查数据库或读取 CSV data {total: 128000, orders: 342} return f销售总额: {data[total]}, 订单数: {data[orders]}这里有两个容易踩坑的地方。第一docstring必须写清楚工具是做什么的、参数是什么含义。模型是读这个描述来决定什么时候调用工具的描述含糊模型就不会调用或者乱传参数。第二返回值最好是文本。工具可以查数据库、读文件、调用外部接口但最终返回给模型的一定要是它能读懂的字符串。不要返回一个复杂的 Python 对象模型看不懂。我在实际项目中见过很多次工具返回了 DataFrame 对象模型直接卡住了日志里只看到一串内存地址。先.to_string()再返回。如果你想让工具支持多种返回格式可以在返回值里放 JSON 字符串同时用docstring说明结构。模型拿到 JSON 后可以自己提取关键信息。3.3 记忆与会话状态先分清短期记忆和长期记忆Agent 的多轮对话不是“记住一切”。你需要明确两类记忆短期记忆当前会话内的上下文把历史消息传给模型通常用消息列表表示。长期记忆跨会话持久化的状态比如用户偏好、历史任务结果存到数据库或向量库。在 LangChain 里最简单的做法是用messages列表保存对话历史from langchain_core.messages import HumanMessage, AIMessage messages [ HumanMessage(content你好帮我看看销售数据), AIMessage(content好的请告诉我日期范围), HumanMessage(content上个月), ]在 LangGraph 里更推荐用checkpointer管理状态它能把每一步的中间状态保存下来宕机、重启后还能恢复。这个机制在生产环境非常重要但入门阶段先不用急着上先用一个简单的消息列表跑通流程。有个边界要注意很多模型有上下文长度限制。如果你把无限长的历史消息都塞给模型很快会触发“最大上下文长度”之类的报错。更合理的做法是只保留最近几轮消息或者先对长文本做摘要再把摘要和最近几轮对话组合起来传给模型。4. 完整实战从“问题路由”到“报告落盘”4.1 项目需求与流程拆解我这次做一个比较通用的实战案例销售数据问答助手。用户输入一个问题Agent 判断是否需要查询销售数据如果需要就调用销售统计工具查询完以后把结果格式化成 Markdown 报告保存到本地文件。这个案例覆盖了 Agent 最核心的四个能力模型调用工具选择与参数生成多轮状态传递输出落盘项目结构可以这样安排sales_assistant/ ├── .env ├── config.py ├── tools.py ├── agent.py └── main.py我一般会把配置、工具、Agent 逻辑拆开避免所有代码堆在一个文件里。等到要加新工具或者把单个工具换成接口调用时改动范围会比较小。4.2 核心代码与最小可运行版本先看tools.py定义两个工具一个查销售统计一个写报告。from langchain_core.tools import tool tool def get_sales_stats(start_date: str, end_date: str) - str: 查询某个日期区间的销售统计。 参数 start_date、end_date 使用 YYYY-MM-DD 格式。 返回包含销售总额和订单数量的文本。 # 这里可以替换成真实的数据库查询或 CSV 读取 stats { start_date: start_date, end_date: end_date, total_amount: 128000, order_count: 342, top_products: A产品, B产品, C产品 } return ( f日期范围: {start_date} 到 {end_date}\n f销售总额: {stats[total_amount]}\n f订单数量: {stats[order_count]}\n f热销产品: {stats[top_products]} ) tool def save_report(content: str, filename: str) - str: 把报告内容保存到本地文件filename 需以 .md 结尾。 with open(filename, w, encodingutf-8) as f: f.write(content) return f报告已保存到 {filename}然后看agent.py用 LangGraph 的create_react_agent搭一个最简 Agentimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent from tools import get_sales_stats, save_report load_dotenv() def build_agent(): llm ChatOpenAI( modelos.getenv(MODEL_NAME, deepseek-chat), api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_API_BASE), temperature0.1, ) tools [get_sales_stats, save_report] agent create_react_agent(llm, tools) return agent agent build_agent()create_react_agent是当前 LangGraph 里比较推荐的高层封装它会自动处理好模型调用、工具执行、结果回传和循环判断。你不需要自己写 ReAct 循环的细节。最后是main.pyfrom agent import agent def run(): result agent.invoke({ messages: [(human, 查询 2025-06-01 到 2025-06-30 的销售统计并把结果保存为 report.md)] }) print(result[messages][-1].content) if __name__ __main__: run()这里的关键是输入要使用messages字典结构这是 LangGraph 的标准状态格式。输出结果也在result[messages]里最后一条消息通常是模型对用户的最终回答。4.3 验证标准与输出检查这个项目跑通以后怎么判断它算成功我一般看四个点模型是否正确理解了用户意图回答了要做什么。模型是否主动调用了get_sales_stats参数里的日期是不是从用户输入里正确提取的。工具结果返回以后模型有没有基于结果继续执行保存动作。最终report.md是否生成内容是否只是模型编造的数据而不是来自工具结果。第二个点尤其重要。模型很可能把日期参数传错或者干脆不调用工具直接编一个数字。所以检查时要看中间过程而不是只看最终输出。我建议先打印每一步的消息确认工具调用参数和结果。4.4 批量任务和日志设计单条任务跑通之后如果你要处理多份报告、多个日期区间就要考虑批量了。批量任务最容易踩的坑有两个一是输出文件命名冲突二是某个任务失败把整个流程卡死。解决方案文件命名加上时间戳或任务 ID比如report_20250601.md。对每个任务做独立 try/except失败时记录日志不要中断后续任务。在 Agent 调用里设置较短的超时时间避免单个请求一直挂住。日志方面我习惯在调用前后打印关键信息logging.info(task_id%s prompt%s, task_id, user_input) logging.info(task_id%s result%s, task_id, final_answer)不要直接打印整个消息对象日志会很长而且可能包含密钥等敏感信息。5. 更复杂场景LangGraph、MCP 与多智能体5.1 什么时候升级到 LangGraph如果你的流程固定是“调用一个工具总结输出”普通 LangChain 链路就够了。但生产级 Agent 通常需要更明确的流程控制。比如先判断用户意图再决定走查询分支还是生成分支。工具调用失败后要自动重试或跳到人工兜底节点。每一步都要记录状态断点续跑。这些需求用create_react_agent已经能覆盖一部分但更复杂的场景需要自己定义图结构。LangGraph 的节点和边可以让你把流程变成一张可控制的图。举个例子我先定义一个“意图判断”节点再决定是把消息交给工具节点还是直接回复。这比让模型自由发挥更可控也更容易排查。5.2 MCP 和 Agent Skill 的边界现在社区里讨论很多的还有 MCPModel Context Protocol和 Agent Skill。这两个概念经常被混在一起其实解决的是不同问题。MCP 解决的是“让 Agent 能统一调用外部工具和数据源”的协议问题。有了 MCP工具可以被注册成标准服务Agent 不需要为每个工具单独写一套协议。对新手来说我的建议是先不要急着学 MCP先把本地工具调用跑稳定。MCP 只是把工具搬到标准协议上工具本身的逻辑和返回格式设计依然是你需要掌握的核心。Agent Skill 更偏向“给智能体预置一套可复用的专业能力”比如一份写报告的模板、一套数据清洗流程。你可以把它理解成一组带有明确说明的专家操作手册Agent 在遇到对应场景时按手册执行。Skill 和 MCP 不是二选一落地时经常混用MCP 管工具接入Skill 管任务方法。5.3 多 Agent 协作的正确姿势很多人一听到 Agent 就想到“多个智能体互相聊天、分工协作”。实际项目里我建议默认不要这么做。多 Agent 会带来三个麻烦上下文互相传递时信息丢失。两个模型互相循环资源消耗成倍增加。排查问题时要同时看多套日志复杂度高很多。更稳的思路是一个主 Agent 负责理解用户意图多个工具负责执行具体任务必要时再按流程拆分出子 Agent。先用“单 Agent 多工具”的架构等真的遇到需要不同角色、不同模型、不同提示词分工的场景再升级成多 Agent。6. 常见报错排查从日志、模型名到上下文6.1 密钥、模型名、Provider 配置问题模型调用报错时第一步不是改代码而是确认三件事密钥是否正确、模型名是否在服务商支持列表里、接口地址是否拼对。常见的错误现象和原因我整理成一张表报错方向常见原因排查顺序401 Unauthorized密钥错误、没有权限、余额不足先检查密钥和环境变量再检查账号权限404 Not Found接口地址不对、模型名不存在确认 base_url 路径、确认模型名拼写400 Bad Request参数格式错误、上下文超长、模型不匹配先看请求体的具体报错信息模型名不支持服务商没有该模型或模型名属于旧版本去官方文档确认当前支持的模型列表我见过最隐蔽的一个问题代码里modeldeepseek-chat但环境变量里OPENAI_API_BASE被设置成了另一个服务商的地址两个服务商的模型名根本不兼容结果一直报 400。排查这类问题要先打印一下实际加载到的配置print(os.getenv(OPENAI_API_BASE)) print(os.getenv(OPENAI_API_KEY)[:10])打印密钥前几位就够了不要完整打印。还有不少工具使用config.toml这类配置文件保存模型设置。如果你改了配置文件但格式不正确或者模型名和当前版本对不上启动时就会直接报错。遇到提示“check your config.toml”的信息不要急着删文件先看看配置文件里model字段填的是什么再对比 API 文档里的支持列表。6.2 上下文超长和“模型不支持”类报错“This models maximum context length is ...”这类报错很常见。模型有上下文窗口限制你把太长的小说、历史消息、工具输出全部塞进去就会超出限制。解决思路按顺序尝试减少历史消息轮数。对长文本做摘要把摘要而不是原文传给模型。把工具返回的大段结果先做截断或汇总再返回给模型。如果是单次输入就超长需要换支持更长上下文的模型或者拆分输入。有些报错是“某个模型版本当前不支持这个操作”。这通常是因为你写死了模型名但服务商已经下架旧版本、升级了新版本。不要迷信网上教程里的模型名直接去接口文档查当前支持的模型列表。模型名填错API 会直接拒绝请求。6.3 工具返回格式和卡住问题的排查顺序Agent 运行卡住或者一直重复调用工具首先要看日志。我推荐的排查顺序是确认日志里有没有工具调用记录参数是什么。确认工具是否真的执行成功返回值是否正常。确认模型是否收到了工具返回值而不是收到一个空值或异常对象。检查模型拿到结果后是否又发起了新的工具调用还是直接卡在死循环里。卡住的常见原因是工具返回内容不符合模型预期。比如模型期待一个 JSON 字符串你返回的是一段普通文本模型无法解析就会再次生成工具调用。另一个原因是工具代码本身抛了异常但没有被捕获Agent 不知道发生了什么只能反复重试。我建议给每个工具内部加上 try/except异常时返回一段能读懂的文本try: result do_something() return f查询成功: {result} except Exception as e: return f查询失败原因: {str(e)}这样模型能根据失败原因决定怎么处理而不是在一个不可见的问题上反复横跳。如果你使用了中间层转发或本地网关类工具来访问模型服务也要注意这些中间层可能把请求指向错误的模型名或者返回不同于官方接口的格式。报错信息里出现“provider”“upstream”之类的字样时先确认你的请求最终打到的是哪台服务端再回头检查代码。6.4 学习资料和概念对照LangChain 中文资料这几年已经很多了但更新速度往往跟不上版本变化。很多老教程还在用 0.1 版本的写法你复制下来直接跑大概率报错。我建议以官方文档和当前发布版的 Release Notes 为准社区文章当作理解概念的辅助材料。如果你看到“LangChain 面试题”这类资料不要死记硬背。真正面试时考官更看重你有没有跑通过一个 Agent知不知道工具返回格式对模型的影响有没有排查过上下文超长的问题。这些才是能写进项目经历里的东西。一句话总结我自己的判断LangChain 作为组件的价值没有消失但真正做复杂 Agent 项目时LangGraph 这类图编排工具会更接近生产要求。入门时把两者一起学先跑通模型调用再做单工具 Agent再做多工具、带状态、带日志的完整项目这条路最稳。