说实话很多初学者学 LangChain 都卡在同一个地方看了官方文档感觉每个概念都认识但真让自己写一个带业务逻辑的智能体又不知道从哪下手。尤其是到了 2026 年LangChain 已经经历了 0.1、0.2、0.3 到 1.x 的多次大版本演进网上的旧教程很多已经跑不通了新版本的 API 又总让人摸不着头脑。这篇文章我想给你一个明确判断LangChain 真正解决的不是“怎么调用大模型”而是“怎么把大模型接进真实的业务流程”。调用一次模型用 requests 就够了但如果你要做的是多轮对话、工具调用、流程编排、模型可替换的工程化应用LangChain 这套抽象才有价值。文章会从最底层的 Model 调用讲起一步步做到一个完整的 Agent 项目——智能客服工单助手。全程都有可运行的 Python 代码你照着敲完就能看到 Agent 自己“决定”查询订单、查 FAQ、甚至创建人工工单。这比单纯背概念有用得多。1. 为什么 2026 年还要学 LangChain先搞清楚它解决什么问题先回答一个最常见的疑问现在大模型这么强很多模型厂商的 SDK 直接调用就很方便为什么还要套一层 LangChain我的观点是如果你只是做一个一次性脚本比如“把这段文本发给模型打印结果”那么直接用模型厂商的 SDK 就够了引入 LangChain 反而增加学习成本。但如果你在做的是一个需要长期维护、多人协作、可能会换模型厂商的业务系统LangChain 的工程化价值就体现出来了。具体来说LangChain 解决的是三类真实痛点。第一类是模型切换成本。企业级项目很少从一开始就定死用哪家大模型。今天可能用 OpenAI明天可能想换成 DeepSeek、通义千问或者智谱。如果没有抽象层换模型意味着把业务代码里的调用逻辑全部重写。LangChain 通过统一的 ChatModel 接口把模型调用封装成一样的 invoke / stream / batch 方法切换模型经常只需要改一行配置。第二类是流程编排。真实业务很少是“一问一答”。你可能有这样的流程先判断用户意图再决定要去查数据库、查知识库还是直接回答最后把结果整理成特定格式。这种多步骤、有分支的逻辑直接写在业务代码里会越来越乱。LangChain 把每一步封装成 Runnable用 LCELLangChain Expression Language像管道一样组合起来这比 if-else 嵌套清晰得多。第三类是 Agent 的自主决策。这是 LangChain 目前最受关注的部分。你给模型一组工具查询订单、查 FAQ、建工单模型根据用户输入自己决定调哪个工具、传什么参数然后根据工具返回结果继续推理直到给出最终答案。这个“模型自己决定下一步”的过程完全靠框架帮你管理循环和上下文自己写工作量很大。所以什么样的读者最应该看这篇文章如果你正在做一个 AI 客服、文档问答助手、流程自动化工具或者你想理解 Agent 到底是怎么运作的这篇文章就是写给你的。如果你只是临时调用一次模型 API那可以先去用官方 SDK。2. LangChain 核心概念从 Model 到 Agent 的完整知识地图学 LangChain 最大的陷阱是“背 API”。因为版本更新太快API 经常变。更可靠的方式是理解它背后的抽象模型。这一节我们把这几个核心概念讲透Model、Prompt、OutputParser、Chain、Tool、Agent、Memory。2.1 Model所有大模型的统一接口LangChain 把不同厂商的模型封装成统一的 ChatModel 对象。你只需要关心几个方法invoke是同步调用stream是流式返回batch是批量处理。底层到底是 GPT 还是 DeepSeek对上层业务透明。这也是 LangChain 最值得称道的设计模型是插件而不是核心依赖。2.2 Prompt对话模板的工程化Prompt 不是简单拼字符串。LangChain 的 ChatPromptTemplate 支持变量占位、消息角色system / user / assistant区分还能自动处理消息历史。这样你可以把提示词当成代码来维护而不是散落在各个调用点。2.3 OutputParser把模型输出变成程序能用的数据模型返回的是字符串。但程序需要的是 JSON、对象或者布尔值。OutputParser 负责把模型输出解析成结构化数据。比如JsonOutputParser会强制要求模型输出合法 JSON并帮你转成 Python 字典。2.4 Chain 与 LCEL把步骤串成管道LCEL 是这个框架的精髓。它用|运算符把 Prompt、Model、OutputParser 组合成一个完整的处理链。比如prompt | llm | parser就是一个标准的三步管道。LCEL 还天然支持流式输出、异步调用、并行执行这是手写函数调用很难做到的。2.5 Tool 与 Agent让模型有“手脚”模型本身只能输出文字不能查数据库、不能调 API。Tool 就是用来扩展模型能力的函数。你把函数注册成 Tool配上描述和参数说明模型就能在需要时“调用”它。Agent 则是“模型 工具 循环决策”的完整封装。它的工作方式可以简单理解为模型根据用户的输入判断需要调用哪个工具框架帮你执行工具并把结果回传给模型模型再根据新信息继续思考和行动直到给出最终答案。2.6 Memory对话记忆存在哪里大模型本身没有记忆每次调用都是独立的。Memory 组件负责把之前的对话历史保存下来下次调用时重新传给模型。但要注意LangChain 1.x 之后更推荐的记忆方案已经不是传统的 Memory 类而是用外部存储管理消息历史或者交给 LangGraph 的状态管理。这个我们后面实战部分会讲到。2.7 LangChain 和 LangGraph 到底是什么关系这是很多人容易混淆的地方。LangChain 是高层组件库适合构建相对固定的调用链和简单的 Agent。而 LangGraph 是 LangChain 团队推出的一个图执行框架它把 Agent 的每一步抽象成图节点节点之间可以跳转、循环、分支状态由框架统一管理。用一句话区分LangChain 让你快速搭出一个能跑的 AgentLangGraph 让你在生产环境里精细控制 Agent 的每一步。维度LangChain AgentLangGraph模型抽象通过 LangChain 模型接口同样基于 LangChain 模型接口流程控制固定的 ReAct 循环自定义图结构支持分支、循环状态管理依赖外部 Memory内置 State 管理器适合场景原型验证、简单工具调用有状态、多步骤、需要人工干预的复杂流程学习成本较低较高如果你现在就做一个单 Agent 小工具用 LangChain 的 AgentExecutor 完全够如果你要做多 Agent 协作、需要打断点人工确认、管理复杂会话状态那就应该研究 LangGraph。3. 环境准备与前置条件在写代码之前先把环境准备好。下面这些步骤我尽量写得简洁但每一步都有它的目的。3.1 Python 环境LangChain 基于 Python建议使用 Python 3.10 或更高版本。如果本机环境比较乱一定要用虚拟环境隔离项目依赖避免不同项目的包互相冲突。python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate3.2 安装 LangChain 核心包pip install langchain langchain-openai langchain-core python-dotenv简单说明一下这几个包langchain主包包含 Agent、Chain、Memory 等高层组件。langchain-openaiOpenAI 兼容模型的适配包代码里用的 ChatOpenAI 就在这里。langchain-core基础抽象像 Prompt、OutputParser、Tool 的定义都在这里。python-dotenv用来读取.env配置文件避免把 API Key 写死在代码里。3.3 配置模型 APILangChain 的优势之一是支持 OpenAI 兼容接口。这意味着你既可以用 OpenAI 官方模型也可以用 DeepSeek、通义千问等提供 OpenAI 兼容端点的模型代码结构几乎不变。在项目根目录创建.env文件# .env OPENAI_API_KEY你的API_KEY OPENAI_BASE_URLhttps://api.deepseek.com/v1这里以 DeepSeek 的 OpenAI 兼容端点为例。如果你用的是 OpenAI 官方把OPENAI_BASE_URL改成官方地址即可。不同厂商的 base_url 写法不完全一样请以你使用的模型服务商最新文档为准。API Key 的获取位置也以对应平台为准不要在代码里硬编码密钥更不要把密钥提交到 Git 仓库。3.4 验证环境是否正常可以先用最简代码验证一下模型是否能通from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage llm ChatOpenAI(modeldeepseek-chat, temperature0) resp llm.invoke([HumanMessage(content你好请回复连接成功)]) print(resp.content)如果输出包含“连接成功”相关的内容说明环境没问题。如果报 401 / 403 错误优先检查 API Key 是否正确如果报模型不存在检查模型名是否和你账号权限匹配。4. Model 模型基础调用从一行代码到工程化这一节我们正式进入代码。先把最基础的 Model 调用跑通再一步步加工程化要素。4.1 最简调用直接把消息发给模型from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage llm ChatOpenAI( modeldeepseek-chat, temperature0.3, ) response llm.invoke([HumanMessage(content用一句话解释什么是数据库索引)]) print(response.content)这段代码做了三件事创建模型对象、构造一条用户消息、同步调用模型。注意invoke接收的不是字符串而是一个消息列表。这是 LangChain 的规范因为对话场景天然是多条消息交替出现的。4.2 统一接口带来的好处切换模型现在假设你要从 deepseek-chat 换成 OpenAI 的 gpt-4o-mini业务代码不需要改动只需要改模型初始化的配置llm ChatOpenAI( modelgpt-4o-mini, temperature0.3, )如果你的 key 不是 OpenAI 官方的而是兼容接口加两个参数指定 base_url 和 api_key 就行。业务逻辑里的invoke、stream、batch全部不用变。这就是抽象层的实际价值。4.3 Prompt 模板别再把字符串拼来拼去在实际项目中系统提示词和用户输入往往需要动态组合。用字符串拼接很容易出错而且无法维护。用 ChatPromptTemplate 会更清晰from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_template( 你是{role}请用不超过{limit}个字回答用户的问题。\n用户问题{question} ) chain prompt | llm result chain.invoke({ role: 专业客服, limit: 50, question: 退款什么时候到账 }) print(result.content)这一步开始出现 LangChain 最有代表性的管道操作符|。prompt | llm表示把 prompt 的输出作为 llm 的输入两者组合成一个新的可调用对象。4.4 结构化输出让模型返回 JSON很多业务场景不需要模型输出自然语言而是需要 JSON 数据比如判断用户意图、抽取关键字段。用 JsonOutputParser 可以让模型输出并解析 JSONfrom langchain_core.output_parsers import JsonOutputParser json_parser JsonOutputParser() format_instruction json_parser.get_format_instructions() prompt ChatPromptTemplate.from_template( 请判断用户问题的意图并返回 JSON。\n 用户问题{question}\n 输出要求{format_instruction} ) chain prompt | llm | json_parser result chain.invoke({ question: 我想查一下昨天买的手机发货没有, format_instruction: format_instruction, }) print(result) print(type(result))运行后你会发现输出不再是字符串而是一个 Python 字典。这样下游代码就可以直接操作字段不需要写正则去解析文本。到这里你已经掌握了 LangChain 最核心的“三层管道”Prompt → Model → OutputParser。这是后面所有复杂功能的地基。5. Agent 智能体运行原理它凭什么能自己“决定”调用工具理解 Agent是这次学习路径里最关键的一步。我们先停下来思考一个问题为什么光有 Chain 不够5.1 Chain 的局限流程是写死的用 Chain 实现一个客服对话流程在你写代码时就已经固定了“先判断意图 → 再查知识库 → 最后回答”。但真实用户问题变化非常多。用户可能直接问退货政策也可能问某个订单到哪了还可能没说两句就要求转人工。如果全用 Chain你得在代码里写大量 if-else。更麻烦的是模型输出的判断不一定完全稳定你很难预期所有的分支组合。Agent 的方案完全不同让模型自己决定调什么工具。你只需要告诉模型“你有这些工具可以用”然后让它根据收到的用户问题自主选择调用顺序和参数。5.2 ReAct 模式思考、行动、观察的循环ReAct 是 Reasoning推理和 Acting行动的组合是目前最主流的 Agent 工作范式。它的核心流程可以概括为下面这个循环用户提问 → Thought模型思考我需要查什么 → Action模型决定调用工具并给出参数 → Observation框架执行工具把结果返回给模型 → Thought模型根据结果继续思考 → Action 或 Final Answer → 直到模型认为可以回答为止这里有个很容易误解的点工具不是模型执行的模型只输出“调用哪个工具、传什么参数”的指令真正执行函数的是框架代码。框架拿到结果后把结果作为 Observation 塞回上下文模型才能看到工具返回了什么。5.3 Tool Calling 协议模型怎么知道有哪些工具这依赖 Tool Calling 机制。LangChain 会把每个工具的“函数签名 描述 参数说明”转换成模型可以理解的 schema随提示词一起发给模型。当模型认为需要查询订单时它输出的不是自然语言“我想查订单”而是一个结构化的工具调用指令。这也是为什么工具的描述要写得足够详细。描述写得好不好直接决定 Agent 在复杂场景下能不能选对工具。写“根据用户订单号查询订单状态返回物流信息”就比写“查订单”好用得多。5.4 AgentExecutor 的执行细节LangChain 将 ReAct 循环封装在 AgentExecutor 里。它的工作流程大概是第一次调用把系统提示词、用户输入、工具列表一起发给模型。模型如果返回 tool_calls框架执行相应工具把结果追加到消息历史中再次调用模型。模型如果返回自然语言说明它认为可以给出最终答案循环终止。为了防止 Agent 陷入工具调用死循环AgentExecutor 通常需要设置最大迭代次数。生产环境里这个参数非常关键后面会专门讲。6. 完整项目实战智能客服工单助手理论知识已经足够现在我们来做一个真正能跑的项目。这个项目不复杂但覆盖了 Agent 的完整生命周期。6.1 项目目标与功能设计我们要做的是一个电商平台智能客服助手。它需要处理三类常见场景用户问常见问题比如退货流程、发货时间、发票问题Agent 应该查询 FAQ 知识库并回答。用户查订单状态Agent 应该调用订单查询工具根据订单号返回状态和物流信息。用户表达投诉或要求人工处理Agent 应该创建工单返回工单号。项目文件结构langchain-agent-demo/ ├── .env # 模型配置 ├── tools.py # 工具函数定义 ├── agent_builder.py # 构建 Agent ├── main.py # 入口程序 └── requirements.txt # 依赖清单6.2 定义工具函数新建tools.py定义三个工具。先看完整代码# tools.py from langchain_core.tools import tool FAQ_DB { 退货流程: 请在订单页申请退货审核通过后48小时内安排取件退款在签收后3个工作日内原路返还。, 发货时间: 现货商品下单后24小时内发货预售商品以页面提示时间为准。, 发票: 您可以在订单详情页申请电子发票系统会在5分钟内发送到您的邮箱。, 修改地址: 订单未发货前可在订单详情页点击“修改地址”自行更新。, 退款到账时间: 退款审核通过后1-3个工作日到账具体以银行处理时间为准。, } ORDER_DB { A1001: {status: 已发货, courier: 顺丰速运, tracking_no: SF123456789}, A1002: {status: 待发货, courier: , tracking_no: }, A1003: {status: 已签收, courier: 中通快递, tracking_no: ZT987654321}, } _work_order_counter 0 tool def query_faq(question: str) - str: 在常见问题知识库中查找答案适合物流、退换货、发票、发货、退款等问题。 normalized question.strip() for key, answer in FAQ_DB.items(): if key in normalized or normalized in key: return answer return 知识库中暂时没有找到对应答案请换个说法再试。 tool def query_order_status(order_id: str) - str: 根据订单号查询订单当前状态返回订单状态、快递公司和运单号。订单号示例A1001。 order_id order_id.strip().upper() order ORDER_DB.get(order_id) if not order: return f未查询到订单 {order_id}请核对订单号。 return ( f订单 {order_id} 当前状态{order[status]} f快递公司{order[courier]} f运单号{order[tracking_no]}。 ) tool def create_work_order(customer_id: str, content: str) - str: 为客户创建人工工单当用户表达投诉、退款争议、要求人工处理时使用。 global _work_order_counter _work_order_counter 1 return ( f已创建工单 WO2026{_work_order_counter:04d} 客服将在2小时内处理。 )这里的关键点是tool装饰器。它把一个普通函数变成了 LangChain 的 Tool 对象。函数名就是工具名docstring 就是工具描述函数参数就是模型的“调用协议”。工具描述非常关键。query_order_status的参数是字符串但模型需要知道“订单号大概长什么样”所以我在描述里加了一句“订单号示例A1001”。这能显著提高模型生成参数的准确性。6.3 构建 Agent新建agent_builder.py# agent_builder.py from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.agents import create_tool_calling_agent, AgentExecutor from tools import query_faq, query_order_status, create_work_order load_dotenv() llm ChatOpenAI(modeldeepseek-chat, temperature0) tools [query_faq, query_order_status, create_work_order] prompt ChatPromptTemplate.from_messages([ ( system, 你是电商平台的智能客服助手。你可以通过工具查询常见问题、 查询订单状态、创建人工工单。回答要简洁、礼貌。 当用户表达强烈不满或要求人工服务时创建工单并告知工单号。 ), (human, {input}), MessagesPlaceholder(agent_scratchpad), ]) agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, )创建 tool-calling Agent 有三个必填参数llm、tools、prompt。prompt 里必须有一个agent_scratchpad的 MessagesPlaceholder这是框架用来记录中间思考和工具调用结果的“草稿区”不能省略。verboseTrue会在控制台打印 Agent 的思考过程和工具调用记录对理解运行机制非常有帮助。6.4 入口程序跑一轮真实对话新建main.py# main.py from agent_builder import agent_executor if __name__ __main__: result agent_executor.invoke({ input: 你好我查一下订单 A1001 现在到哪了 }) print(最终回答, result[output])6.5 运行与验证在虚拟环境中运行python main.py如果一切正常你会看到类似下面的输出细节会因模型略有不同 Entering new AgentExecutor chain... Invoking: query_order_status with {order_id: A1001} 订单 A1001 当前状态已发货快递公司顺丰速运运单号SF123456789。 Finished chain. 最终回答 您的订单 A1001 已经发货快递公司是顺丰速运运单号是 SF123456789。看到 “Invoking: 工具名” 这一行说明 Agent 确实调用了工具而不是机械地把问题复述一遍。为了验证 Agent 的决策能力建议你按下面的用例逐条测试测试输入预期行为判断标准退货流程是什么调用 query_faq回答中包含退货申请、审核、退款时间订单 B9999 什么状态调用 query_order_status提示未查询到订单并要求核对订单号你们的客服态度太差了我要投诉调用 create_work_order返回工单号帮我查一下 A1002 的单号调用 query_order_status返回待发货状态如果某一类问题 Agent 没有调用对应工具先不要怀疑模型优先检查工具描述是否清晰。7. 常见问题与排查思路在跑 Agent 的过程中你可能遇到各种报错。下面是我根据实际经验整理的高频问题清单建议收藏对照排查。问题现象可能原因排查方式解决方案安装依赖后 import langchain 报错依赖版本冲突查看完整堆栈打印依赖树pip freeze新建干净虚拟环境重装调用模型报 401 / AuthenticationErrorAPI Key 无效、过期检查 .env 是否加载打印 key 末尾几位重新生成 Key确认环境变量已生效调用模型报 400提示模型不存在模型名不属于当前账号或服务商核对模型名大小写和可用列表换成账号有权限的模型名Agent 不调用工具直接给答案工具描述不清晰或模型不支持 tool calling开启 verbose 查看模型输出优化工具描述换成支持 function calling 的模型Agent 反复调用同一个工具停不下来模型认为信息不足或者工具返回结果不完整查看 Observation 内容是否包含足够信息在工具返回值里补充状态说明设置 max_iterations 兜底多轮对话后上下文超长工具调用过程累积太多消息查看控制台打印的消息数量精简工具输出减少历史轮次使用更长上下文的模型使用部分推理模型时报 400提示 reasoning_content 必须回传推理模型要求把上一轮思维链内容传回 API通用框架未必自动处理该字段把完整报错信息发给模型服务商确认改用非推理对话模型或确认框架对特殊字段的透传支持这里特别提一下最后一条。如果你用的是 DeepSeek 等厂商的推理模型多轮调用时可能遇到类似the reasoning_content in the thinking mode must be passed back to the api的 400 错误。这类报错通常和推理模型要求回传特殊字段有关通用 Agent 框架不一定默认支持。最稳妥的解决方案是在 Agent 场景里切换到非推理对话模型比如deepseek-chat或者查看你所用框架是否已适配该厂商的特殊字段。8. 最佳实践与工程建议Demo 跑通只是一个开始。如果要把 Agent 放到真实项目里下面这些工程建议值得你认真对待。8.1 模型层统一配置与降级策略模型名和 base_url 不要硬编码在代码里应该放到环境变量或配置中心。生产环境建议配置主模型和备用模型当主模型限流或故障时可以自动降级到备用模型。网络上常能看到类似 “selected model is at capacity. please try a different model” 的报错这就是模型侧容量不足的信号具备降级能力能避免线上事故。8.2 Prompt 层系统提示词要写“使用边界”在系统提示词里写清楚“什么场景用哪个工具”比让模型自己漫无目的地猜测可靠得多。比如“当用户表达强烈不满或要求人工服务时创建工单并告知工单号。”这样就给了模型明确的决策边界。8.3 工具层参数校验和副作用控制工具是 Agent 连接真实系统的窗口也是最容易出问题的环节。每个工具都应该做参数校验比如订单号格式不对就返回明确错误而不是抛异常。涉及写操作的工具比如创建工单、修改订单一定要先在小范围验证并且记录完整的调用日志。如果工具会触发真实业务副作用建议在代码层面加“人工确认”或者“测试模式”开关。8.4 安全边界最小权限原则这一点非常重要。Agent 能调用的工具必须遵守最小权限原则——只开放它完成当前任务真正必要的工具。涉及支付、删除、修改敏感信息的操作绝对不能直接交给模型自主决策。更稳妥的做法是让 Agent 只负责信息收集和方案生成最终执行权保留在人工或受控流程中。8.5 可观测性每一次工具调用都要能追溯生产环境的 Agent 不能用 console 输出来排查问题。建议记录完整的会话 ID、每轮消息、模型输出、工具调用参数和返回结果。这样当用户投诉“为什么助手给了我一个错误答案”时你能快速回放整个决策过程定位是模型判断错误还是工具返回了脏数据。8.6 性能与成本控制Agent 的一个显著特点是多次调用模型。一个简单的工具调用循环可能产生 3 到 5 次模型请求成本和延迟都会成倍增加。建议从三方面控制设置max_iterations上限让工具返回精简的结构化文本避免把大段无关数据塞进上下文对重复性问答增加缓存命中缓存就直接返回。9. 总结与后续学习方向这篇文章的核心脉络可以概括成三句话。第一LangChain 是 LLM 应用的工程化框架模型调用只是它的起点真正有价值的是 Prompt、OutputParser、Tool 这些可组合的抽象。第二Agent 的本质是“模型自主决策 工具执行 循环迭代”。LangChain 的 AgentExecutor 帮你管理了 ReAct 循环你要做的是把工具定义好、描述写清楚、边界划明白。第三单 Agent 小项目用 AgentExecutor 足够但如果你要做有状态、多分支、需要人工介入的复杂系统下一步应该学习 LangGraph。它把 Agent 的每一步变成可控的图节点是 LangChain 生态里更贴近生产的方向。建议你先把这个客服 demo 完整跑通再逐步扩展给工具接上真实数据库、把 FAQ 换成向量检索RAG、增加多轮对话记忆。研究 MCPModel Context Protocol也是一个很好的方向它正在成为模型连接外部工具的标准协议。学习的路径很多但核心仍然是先跑通一个最小闭环再往上叠加复杂度。代码在本地跑起来比收藏十篇教程都管用。 从模型到智能体：LangChain实战构建客服工单助手
说实话很多初学者学 LangChain 都卡在同一个地方看了官方文档感觉每个概念都认识但真让自己写一个带业务逻辑的智能体又不知道从哪下手。尤其是到了 2026 年LangChain 已经经历了 0.1、0.2、0.3 到 1.x 的多次大版本演进网上的旧教程很多已经跑不通了新版本的 API 又总让人摸不着头脑。这篇文章我想给你一个明确判断LangChain 真正解决的不是“怎么调用大模型”而是“怎么把大模型接进真实的业务流程”。调用一次模型用 requests 就够了但如果你要做的是多轮对话、工具调用、流程编排、模型可替换的工程化应用LangChain 这套抽象才有价值。文章会从最底层的 Model 调用讲起一步步做到一个完整的 Agent 项目——智能客服工单助手。全程都有可运行的 Python 代码你照着敲完就能看到 Agent 自己“决定”查询订单、查 FAQ、甚至创建人工工单。这比单纯背概念有用得多。1. 为什么 2026 年还要学 LangChain先搞清楚它解决什么问题先回答一个最常见的疑问现在大模型这么强很多模型厂商的 SDK 直接调用就很方便为什么还要套一层 LangChain我的观点是如果你只是做一个一次性脚本比如“把这段文本发给模型打印结果”那么直接用模型厂商的 SDK 就够了引入 LangChain 反而增加学习成本。但如果你在做的是一个需要长期维护、多人协作、可能会换模型厂商的业务系统LangChain 的工程化价值就体现出来了。具体来说LangChain 解决的是三类真实痛点。第一类是模型切换成本。企业级项目很少从一开始就定死用哪家大模型。今天可能用 OpenAI明天可能想换成 DeepSeek、通义千问或者智谱。如果没有抽象层换模型意味着把业务代码里的调用逻辑全部重写。LangChain 通过统一的 ChatModel 接口把模型调用封装成一样的 invoke / stream / batch 方法切换模型经常只需要改一行配置。第二类是流程编排。真实业务很少是“一问一答”。你可能有这样的流程先判断用户意图再决定要去查数据库、查知识库还是直接回答最后把结果整理成特定格式。这种多步骤、有分支的逻辑直接写在业务代码里会越来越乱。LangChain 把每一步封装成 Runnable用 LCELLangChain Expression Language像管道一样组合起来这比 if-else 嵌套清晰得多。第三类是 Agent 的自主决策。这是 LangChain 目前最受关注的部分。你给模型一组工具查询订单、查 FAQ、建工单模型根据用户输入自己决定调哪个工具、传什么参数然后根据工具返回结果继续推理直到给出最终答案。这个“模型自己决定下一步”的过程完全靠框架帮你管理循环和上下文自己写工作量很大。所以什么样的读者最应该看这篇文章如果你正在做一个 AI 客服、文档问答助手、流程自动化工具或者你想理解 Agent 到底是怎么运作的这篇文章就是写给你的。如果你只是临时调用一次模型 API那可以先去用官方 SDK。2. LangChain 核心概念从 Model 到 Agent 的完整知识地图学 LangChain 最大的陷阱是“背 API”。因为版本更新太快API 经常变。更可靠的方式是理解它背后的抽象模型。这一节我们把这几个核心概念讲透Model、Prompt、OutputParser、Chain、Tool、Agent、Memory。2.1 Model所有大模型的统一接口LangChain 把不同厂商的模型封装成统一的 ChatModel 对象。你只需要关心几个方法invoke是同步调用stream是流式返回batch是批量处理。底层到底是 GPT 还是 DeepSeek对上层业务透明。这也是 LangChain 最值得称道的设计模型是插件而不是核心依赖。2.2 Prompt对话模板的工程化Prompt 不是简单拼字符串。LangChain 的 ChatPromptTemplate 支持变量占位、消息角色system / user / assistant区分还能自动处理消息历史。这样你可以把提示词当成代码来维护而不是散落在各个调用点。2.3 OutputParser把模型输出变成程序能用的数据模型返回的是字符串。但程序需要的是 JSON、对象或者布尔值。OutputParser 负责把模型输出解析成结构化数据。比如JsonOutputParser会强制要求模型输出合法 JSON并帮你转成 Python 字典。2.4 Chain 与 LCEL把步骤串成管道LCEL 是这个框架的精髓。它用|运算符把 Prompt、Model、OutputParser 组合成一个完整的处理链。比如prompt | llm | parser就是一个标准的三步管道。LCEL 还天然支持流式输出、异步调用、并行执行这是手写函数调用很难做到的。2.5 Tool 与 Agent让模型有“手脚”模型本身只能输出文字不能查数据库、不能调 API。Tool 就是用来扩展模型能力的函数。你把函数注册成 Tool配上描述和参数说明模型就能在需要时“调用”它。Agent 则是“模型 工具 循环决策”的完整封装。它的工作方式可以简单理解为模型根据用户的输入判断需要调用哪个工具框架帮你执行工具并把结果回传给模型模型再根据新信息继续思考和行动直到给出最终答案。2.6 Memory对话记忆存在哪里大模型本身没有记忆每次调用都是独立的。Memory 组件负责把之前的对话历史保存下来下次调用时重新传给模型。但要注意LangChain 1.x 之后更推荐的记忆方案已经不是传统的 Memory 类而是用外部存储管理消息历史或者交给 LangGraph 的状态管理。这个我们后面实战部分会讲到。2.7 LangChain 和 LangGraph 到底是什么关系这是很多人容易混淆的地方。LangChain 是高层组件库适合构建相对固定的调用链和简单的 Agent。而 LangGraph 是 LangChain 团队推出的一个图执行框架它把 Agent 的每一步抽象成图节点节点之间可以跳转、循环、分支状态由框架统一管理。用一句话区分LangChain 让你快速搭出一个能跑的 AgentLangGraph 让你在生产环境里精细控制 Agent 的每一步。维度LangChain AgentLangGraph模型抽象通过 LangChain 模型接口同样基于 LangChain 模型接口流程控制固定的 ReAct 循环自定义图结构支持分支、循环状态管理依赖外部 Memory内置 State 管理器适合场景原型验证、简单工具调用有状态、多步骤、需要人工干预的复杂流程学习成本较低较高如果你现在就做一个单 Agent 小工具用 LangChain 的 AgentExecutor 完全够如果你要做多 Agent 协作、需要打断点人工确认、管理复杂会话状态那就应该研究 LangGraph。3. 环境准备与前置条件在写代码之前先把环境准备好。下面这些步骤我尽量写得简洁但每一步都有它的目的。3.1 Python 环境LangChain 基于 Python建议使用 Python 3.10 或更高版本。如果本机环境比较乱一定要用虚拟环境隔离项目依赖避免不同项目的包互相冲突。python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate3.2 安装 LangChain 核心包pip install langchain langchain-openai langchain-core python-dotenv简单说明一下这几个包langchain主包包含 Agent、Chain、Memory 等高层组件。langchain-openaiOpenAI 兼容模型的适配包代码里用的 ChatOpenAI 就在这里。langchain-core基础抽象像 Prompt、OutputParser、Tool 的定义都在这里。python-dotenv用来读取.env配置文件避免把 API Key 写死在代码里。3.3 配置模型 APILangChain 的优势之一是支持 OpenAI 兼容接口。这意味着你既可以用 OpenAI 官方模型也可以用 DeepSeek、通义千问等提供 OpenAI 兼容端点的模型代码结构几乎不变。在项目根目录创建.env文件# .env OPENAI_API_KEY你的API_KEY OPENAI_BASE_URLhttps://api.deepseek.com/v1这里以 DeepSeek 的 OpenAI 兼容端点为例。如果你用的是 OpenAI 官方把OPENAI_BASE_URL改成官方地址即可。不同厂商的 base_url 写法不完全一样请以你使用的模型服务商最新文档为准。API Key 的获取位置也以对应平台为准不要在代码里硬编码密钥更不要把密钥提交到 Git 仓库。3.4 验证环境是否正常可以先用最简代码验证一下模型是否能通from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage llm ChatOpenAI(modeldeepseek-chat, temperature0) resp llm.invoke([HumanMessage(content你好请回复连接成功)]) print(resp.content)如果输出包含“连接成功”相关的内容说明环境没问题。如果报 401 / 403 错误优先检查 API Key 是否正确如果报模型不存在检查模型名是否和你账号权限匹配。4. Model 模型基础调用从一行代码到工程化这一节我们正式进入代码。先把最基础的 Model 调用跑通再一步步加工程化要素。4.1 最简调用直接把消息发给模型from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage llm ChatOpenAI( modeldeepseek-chat, temperature0.3, ) response llm.invoke([HumanMessage(content用一句话解释什么是数据库索引)]) print(response.content)这段代码做了三件事创建模型对象、构造一条用户消息、同步调用模型。注意invoke接收的不是字符串而是一个消息列表。这是 LangChain 的规范因为对话场景天然是多条消息交替出现的。4.2 统一接口带来的好处切换模型现在假设你要从 deepseek-chat 换成 OpenAI 的 gpt-4o-mini业务代码不需要改动只需要改模型初始化的配置llm ChatOpenAI( modelgpt-4o-mini, temperature0.3, )如果你的 key 不是 OpenAI 官方的而是兼容接口加两个参数指定 base_url 和 api_key 就行。业务逻辑里的invoke、stream、batch全部不用变。这就是抽象层的实际价值。4.3 Prompt 模板别再把字符串拼来拼去在实际项目中系统提示词和用户输入往往需要动态组合。用字符串拼接很容易出错而且无法维护。用 ChatPromptTemplate 会更清晰from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_template( 你是{role}请用不超过{limit}个字回答用户的问题。\n用户问题{question} ) chain prompt | llm result chain.invoke({ role: 专业客服, limit: 50, question: 退款什么时候到账 }) print(result.content)这一步开始出现 LangChain 最有代表性的管道操作符|。prompt | llm表示把 prompt 的输出作为 llm 的输入两者组合成一个新的可调用对象。4.4 结构化输出让模型返回 JSON很多业务场景不需要模型输出自然语言而是需要 JSON 数据比如判断用户意图、抽取关键字段。用 JsonOutputParser 可以让模型输出并解析 JSONfrom langchain_core.output_parsers import JsonOutputParser json_parser JsonOutputParser() format_instruction json_parser.get_format_instructions() prompt ChatPromptTemplate.from_template( 请判断用户问题的意图并返回 JSON。\n 用户问题{question}\n 输出要求{format_instruction} ) chain prompt | llm | json_parser result chain.invoke({ question: 我想查一下昨天买的手机发货没有, format_instruction: format_instruction, }) print(result) print(type(result))运行后你会发现输出不再是字符串而是一个 Python 字典。这样下游代码就可以直接操作字段不需要写正则去解析文本。到这里你已经掌握了 LangChain 最核心的“三层管道”Prompt → Model → OutputParser。这是后面所有复杂功能的地基。5. Agent 智能体运行原理它凭什么能自己“决定”调用工具理解 Agent是这次学习路径里最关键的一步。我们先停下来思考一个问题为什么光有 Chain 不够5.1 Chain 的局限流程是写死的用 Chain 实现一个客服对话流程在你写代码时就已经固定了“先判断意图 → 再查知识库 → 最后回答”。但真实用户问题变化非常多。用户可能直接问退货政策也可能问某个订单到哪了还可能没说两句就要求转人工。如果全用 Chain你得在代码里写大量 if-else。更麻烦的是模型输出的判断不一定完全稳定你很难预期所有的分支组合。Agent 的方案完全不同让模型自己决定调什么工具。你只需要告诉模型“你有这些工具可以用”然后让它根据收到的用户问题自主选择调用顺序和参数。5.2 ReAct 模式思考、行动、观察的循环ReAct 是 Reasoning推理和 Acting行动的组合是目前最主流的 Agent 工作范式。它的核心流程可以概括为下面这个循环用户提问 → Thought模型思考我需要查什么 → Action模型决定调用工具并给出参数 → Observation框架执行工具把结果返回给模型 → Thought模型根据结果继续思考 → Action 或 Final Answer → 直到模型认为可以回答为止这里有个很容易误解的点工具不是模型执行的模型只输出“调用哪个工具、传什么参数”的指令真正执行函数的是框架代码。框架拿到结果后把结果作为 Observation 塞回上下文模型才能看到工具返回了什么。5.3 Tool Calling 协议模型怎么知道有哪些工具这依赖 Tool Calling 机制。LangChain 会把每个工具的“函数签名 描述 参数说明”转换成模型可以理解的 schema随提示词一起发给模型。当模型认为需要查询订单时它输出的不是自然语言“我想查订单”而是一个结构化的工具调用指令。这也是为什么工具的描述要写得足够详细。描述写得好不好直接决定 Agent 在复杂场景下能不能选对工具。写“根据用户订单号查询订单状态返回物流信息”就比写“查订单”好用得多。5.4 AgentExecutor 的执行细节LangChain 将 ReAct 循环封装在 AgentExecutor 里。它的工作流程大概是第一次调用把系统提示词、用户输入、工具列表一起发给模型。模型如果返回 tool_calls框架执行相应工具把结果追加到消息历史中再次调用模型。模型如果返回自然语言说明它认为可以给出最终答案循环终止。为了防止 Agent 陷入工具调用死循环AgentExecutor 通常需要设置最大迭代次数。生产环境里这个参数非常关键后面会专门讲。6. 完整项目实战智能客服工单助手理论知识已经足够现在我们来做一个真正能跑的项目。这个项目不复杂但覆盖了 Agent 的完整生命周期。6.1 项目目标与功能设计我们要做的是一个电商平台智能客服助手。它需要处理三类常见场景用户问常见问题比如退货流程、发货时间、发票问题Agent 应该查询 FAQ 知识库并回答。用户查订单状态Agent 应该调用订单查询工具根据订单号返回状态和物流信息。用户表达投诉或要求人工处理Agent 应该创建工单返回工单号。项目文件结构langchain-agent-demo/ ├── .env # 模型配置 ├── tools.py # 工具函数定义 ├── agent_builder.py # 构建 Agent ├── main.py # 入口程序 └── requirements.txt # 依赖清单6.2 定义工具函数新建tools.py定义三个工具。先看完整代码# tools.py from langchain_core.tools import tool FAQ_DB { 退货流程: 请在订单页申请退货审核通过后48小时内安排取件退款在签收后3个工作日内原路返还。, 发货时间: 现货商品下单后24小时内发货预售商品以页面提示时间为准。, 发票: 您可以在订单详情页申请电子发票系统会在5分钟内发送到您的邮箱。, 修改地址: 订单未发货前可在订单详情页点击“修改地址”自行更新。, 退款到账时间: 退款审核通过后1-3个工作日到账具体以银行处理时间为准。, } ORDER_DB { A1001: {status: 已发货, courier: 顺丰速运, tracking_no: SF123456789}, A1002: {status: 待发货, courier: , tracking_no: }, A1003: {status: 已签收, courier: 中通快递, tracking_no: ZT987654321}, } _work_order_counter 0 tool def query_faq(question: str) - str: 在常见问题知识库中查找答案适合物流、退换货、发票、发货、退款等问题。 normalized question.strip() for key, answer in FAQ_DB.items(): if key in normalized or normalized in key: return answer return 知识库中暂时没有找到对应答案请换个说法再试。 tool def query_order_status(order_id: str) - str: 根据订单号查询订单当前状态返回订单状态、快递公司和运单号。订单号示例A1001。 order_id order_id.strip().upper() order ORDER_DB.get(order_id) if not order: return f未查询到订单 {order_id}请核对订单号。 return ( f订单 {order_id} 当前状态{order[status]} f快递公司{order[courier]} f运单号{order[tracking_no]}。 ) tool def create_work_order(customer_id: str, content: str) - str: 为客户创建人工工单当用户表达投诉、退款争议、要求人工处理时使用。 global _work_order_counter _work_order_counter 1 return ( f已创建工单 WO2026{_work_order_counter:04d} 客服将在2小时内处理。 )这里的关键点是tool装饰器。它把一个普通函数变成了 LangChain 的 Tool 对象。函数名就是工具名docstring 就是工具描述函数参数就是模型的“调用协议”。工具描述非常关键。query_order_status的参数是字符串但模型需要知道“订单号大概长什么样”所以我在描述里加了一句“订单号示例A1001”。这能显著提高模型生成参数的准确性。6.3 构建 Agent新建agent_builder.py# agent_builder.py from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.agents import create_tool_calling_agent, AgentExecutor from tools import query_faq, query_order_status, create_work_order load_dotenv() llm ChatOpenAI(modeldeepseek-chat, temperature0) tools [query_faq, query_order_status, create_work_order] prompt ChatPromptTemplate.from_messages([ ( system, 你是电商平台的智能客服助手。你可以通过工具查询常见问题、 查询订单状态、创建人工工单。回答要简洁、礼貌。 当用户表达强烈不满或要求人工服务时创建工单并告知工单号。 ), (human, {input}), MessagesPlaceholder(agent_scratchpad), ]) agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, )创建 tool-calling Agent 有三个必填参数llm、tools、prompt。prompt 里必须有一个agent_scratchpad的 MessagesPlaceholder这是框架用来记录中间思考和工具调用结果的“草稿区”不能省略。verboseTrue会在控制台打印 Agent 的思考过程和工具调用记录对理解运行机制非常有帮助。6.4 入口程序跑一轮真实对话新建main.py# main.py from agent_builder import agent_executor if __name__ __main__: result agent_executor.invoke({ input: 你好我查一下订单 A1001 现在到哪了 }) print(最终回答, result[output])6.5 运行与验证在虚拟环境中运行python main.py如果一切正常你会看到类似下面的输出细节会因模型略有不同 Entering new AgentExecutor chain... Invoking: query_order_status with {order_id: A1001} 订单 A1001 当前状态已发货快递公司顺丰速运运单号SF123456789。 Finished chain. 最终回答 您的订单 A1001 已经发货快递公司是顺丰速运运单号是 SF123456789。看到 “Invoking: 工具名” 这一行说明 Agent 确实调用了工具而不是机械地把问题复述一遍。为了验证 Agent 的决策能力建议你按下面的用例逐条测试测试输入预期行为判断标准退货流程是什么调用 query_faq回答中包含退货申请、审核、退款时间订单 B9999 什么状态调用 query_order_status提示未查询到订单并要求核对订单号你们的客服态度太差了我要投诉调用 create_work_order返回工单号帮我查一下 A1002 的单号调用 query_order_status返回待发货状态如果某一类问题 Agent 没有调用对应工具先不要怀疑模型优先检查工具描述是否清晰。7. 常见问题与排查思路在跑 Agent 的过程中你可能遇到各种报错。下面是我根据实际经验整理的高频问题清单建议收藏对照排查。问题现象可能原因排查方式解决方案安装依赖后 import langchain 报错依赖版本冲突查看完整堆栈打印依赖树pip freeze新建干净虚拟环境重装调用模型报 401 / AuthenticationErrorAPI Key 无效、过期检查 .env 是否加载打印 key 末尾几位重新生成 Key确认环境变量已生效调用模型报 400提示模型不存在模型名不属于当前账号或服务商核对模型名大小写和可用列表换成账号有权限的模型名Agent 不调用工具直接给答案工具描述不清晰或模型不支持 tool calling开启 verbose 查看模型输出优化工具描述换成支持 function calling 的模型Agent 反复调用同一个工具停不下来模型认为信息不足或者工具返回结果不完整查看 Observation 内容是否包含足够信息在工具返回值里补充状态说明设置 max_iterations 兜底多轮对话后上下文超长工具调用过程累积太多消息查看控制台打印的消息数量精简工具输出减少历史轮次使用更长上下文的模型使用部分推理模型时报 400提示 reasoning_content 必须回传推理模型要求把上一轮思维链内容传回 API通用框架未必自动处理该字段把完整报错信息发给模型服务商确认改用非推理对话模型或确认框架对特殊字段的透传支持这里特别提一下最后一条。如果你用的是 DeepSeek 等厂商的推理模型多轮调用时可能遇到类似the reasoning_content in the thinking mode must be passed back to the api的 400 错误。这类报错通常和推理模型要求回传特殊字段有关通用 Agent 框架不一定默认支持。最稳妥的解决方案是在 Agent 场景里切换到非推理对话模型比如deepseek-chat或者查看你所用框架是否已适配该厂商的特殊字段。8. 最佳实践与工程建议Demo 跑通只是一个开始。如果要把 Agent 放到真实项目里下面这些工程建议值得你认真对待。8.1 模型层统一配置与降级策略模型名和 base_url 不要硬编码在代码里应该放到环境变量或配置中心。生产环境建议配置主模型和备用模型当主模型限流或故障时可以自动降级到备用模型。网络上常能看到类似 “selected model is at capacity. please try a different model” 的报错这就是模型侧容量不足的信号具备降级能力能避免线上事故。8.2 Prompt 层系统提示词要写“使用边界”在系统提示词里写清楚“什么场景用哪个工具”比让模型自己漫无目的地猜测可靠得多。比如“当用户表达强烈不满或要求人工服务时创建工单并告知工单号。”这样就给了模型明确的决策边界。8.3 工具层参数校验和副作用控制工具是 Agent 连接真实系统的窗口也是最容易出问题的环节。每个工具都应该做参数校验比如订单号格式不对就返回明确错误而不是抛异常。涉及写操作的工具比如创建工单、修改订单一定要先在小范围验证并且记录完整的调用日志。如果工具会触发真实业务副作用建议在代码层面加“人工确认”或者“测试模式”开关。8.4 安全边界最小权限原则这一点非常重要。Agent 能调用的工具必须遵守最小权限原则——只开放它完成当前任务真正必要的工具。涉及支付、删除、修改敏感信息的操作绝对不能直接交给模型自主决策。更稳妥的做法是让 Agent 只负责信息收集和方案生成最终执行权保留在人工或受控流程中。8.5 可观测性每一次工具调用都要能追溯生产环境的 Agent 不能用 console 输出来排查问题。建议记录完整的会话 ID、每轮消息、模型输出、工具调用参数和返回结果。这样当用户投诉“为什么助手给了我一个错误答案”时你能快速回放整个决策过程定位是模型判断错误还是工具返回了脏数据。8.6 性能与成本控制Agent 的一个显著特点是多次调用模型。一个简单的工具调用循环可能产生 3 到 5 次模型请求成本和延迟都会成倍增加。建议从三方面控制设置max_iterations上限让工具返回精简的结构化文本避免把大段无关数据塞进上下文对重复性问答增加缓存命中缓存就直接返回。9. 总结与后续学习方向这篇文章的核心脉络可以概括成三句话。第一LangChain 是 LLM 应用的工程化框架模型调用只是它的起点真正有价值的是 Prompt、OutputParser、Tool 这些可组合的抽象。第二Agent 的本质是“模型自主决策 工具执行 循环迭代”。LangChain 的 AgentExecutor 帮你管理了 ReAct 循环你要做的是把工具定义好、描述写清楚、边界划明白。第三单 Agent 小项目用 AgentExecutor 足够但如果你要做有状态、多分支、需要人工介入的复杂系统下一步应该学习 LangGraph。它把 Agent 的每一步变成可控的图节点是 LangChain 生态里更贴近生产的方向。建议你先把这个客服 demo 完整跑通再逐步扩展给工具接上真实数据库、把 FAQ 换成向量检索RAG、增加多轮对话记忆。研究 MCPModel Context Protocol也是一个很好的方向它正在成为模型连接外部工具的标准协议。学习的路径很多但核心仍然是先跑通一个最小闭环再往上叠加复杂度。代码在本地跑起来比收藏十篇教程都管用。