聊到Agent开发很多人第一反应是“让模型自己决定”可真正写起业务代码时才明白模型只负责“想”真正让Agent稳定干活的是围绕在它外面的一圈管路和阀门。这些管路在LangChain里就是内置中间件。这篇不讲高深理论直接把这些为Agent准备的内置中间件挨个捋清楚从提示模板到输出解析器从记忆到工具封装再通过一个能直接照抄的客服Agent示例让你知道每层组件在什么位置、解决什么问题、有哪些实战中的坑。适合刚接触LangChain不久、想把Agent真正用起来的开发者。1. 先搞清楚“LangChain内置中间件”到底是什么1.1 Agent的执行链路与中间件定位先看一个最常见的误解有人以为Agent就是“模型 提示词”跑起来会自动干活。实际上一个没有中间件的裸Agent是非常脆弱的你丢给它一句话它可能答非所问可能编造工具结果也可能在同一个步骤里反复横跳。问题不在于模型而是缺少了夹在“模型”和“业务”之间的那层处理逻辑。在LangChain里Agent的执行链路大体是这样的先接收用户输入然后从Prompt模板里组装出完整指令交给模型推理模型决定调用哪个工具LangChain去执行工具并把结果喂回模型模型再基于观察继续推理直到给出最终答案。这个链路里每一步的前后都需要有组件做“翻译”和“状态管理”而这些组件就是我们说的中间件。把LangChain内置中间件想象成一家餐厅的后厨流程前台接单用户输入菜单设计Prompt模板传菜员工具执行品控员输出解析账本记录记忆监控摄像头回调。任何一个环节缺失整个服务都会混乱。1.2 内置中间件的完整分类LangChain内置的中间件种类并不算少但如果按功能划分基本可以归纳为五类中间件核心职责常见具体组件提示模板管理给模型的指令注入上下文和变量PromptTemplate、ChatPromptTemplate输出解析把模型的自然语言回复转成结构化数据PydanticOutputParser、StructuredOutputParser记忆管理保存历史对话和摘要维护多轮状态ConversationBufferMemory、ConversationSummaryBufferMemory工具封装把业务函数变成模型可调用的“能力接口”Tool、tool装饰器、Toolkits回调与观测记录Agent每步动作方便调试和追踪BaseCallbackHandler、ConsoleCallbackHandler有人会把“模型本身”也算成中间件其实不太准确。模型是Agent的核心动力源中间件是包裹在外的支持系统。真正有价值的工程化工作也恰恰集中在这五类中间件上。2. 逐类拆解五个核心内置中间件2.1 提示模板中间件不要每次手写系统提示词刚开始写Agent时我喜欢在代码里直接拼字符串比如“system: 你是一个客服用户问题是xxx”。这种写法在Demo里没问题但一旦做多轮对话、多场景并发你会发现代码又乱又难维护。PromptTemplate的价值在于把提示词变成可复用的模板变量体系。比如在LangChain里用ChatPromptTemplate可以清晰地区分系统消息、人类消息、AI消息from langchain.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是{shop_name}的智能客服可以查询订单、物流、退款信息。回答务必简洁。), (human, {input}) ])注意{shop_name}和{input}都是变量。实际调用时传入prompt.invoke({shop_name: 某店铺, input: 我要查订单})模板会把消息组装好。好处很明显不同店铺、不同业务线可以复用同一个模板结构只需要换参数。更进阶的用法是给模板加少数示例Few-Shot。比如一个意图识别Agent可以在模板里先给一个“用户问快递 - 查询物流”的示例再让模型做新分类。这种中间件直接影响了模型后续表现属于性价比最高的优化点。这里有一个实战心得模板里的System指令不要写得过长。很多人爱把规则一条条堆到几百字发现Agent还是爱答非所问。其实跟写接口文档一样指令要精简、分块、给优先级。把最关键的约束放前头比一股脑塞给模型更有效。2.2 输出解析中间件把模型的“话”变成程序能用的“数据”模型回复本质上是一段文本程序不能直接拿来做分支判断。这时输出解析中间件就派上用场了。LangChain内置了多种解析器最常用的是PydanticOutputParser定义好目标数据结构解析器会引导模型按JSON格式输出再校验成我们需要的对象。看一个实际例子假设客服Agent需要先判断用户意图from pydantic import BaseModel, Field from langchain.output_parsers import PydanticOutputParser class IntentResult(BaseModel): intent: str Field(description用户意图取值只能是订单查询、物流查询、退款申请、其他) order_id: str | None Field(defaultNone, description用户提到的订单号没有则为null) confidence: float Field(description置信度0到1之间) parser PydanticOutputParser(pydantic_objectIntentResult)使用的时候把parser.get_format_instructions()拼进Prompt模板让模型按照指定格式返回。拿到回复后调用parser.parse(llm_output)就能得到IntentResult对象。如果模型输出不合法解析器会抛出异常我们可以捕获后重新让模型修正一次。这背后有个设计逻辑输出解析不是“事后修正”而是“过程约束”。只要Prompt里明确说了“必须返回JSON字段包括xxx”模型生成非法结果的概率会大幅降低。所以别等着出错再补异常先把这个中间件用起来会有立竿见影的效果。2.3 记忆中间件让Agent记住上下文没有记忆的Agent每次对话都是“初次见面”。你可以把上一轮内容拼进Prompt但很快会发现Token占用越来越大而且真正重要的历史信息被淹没在一堆废话里。LangChain内置了几种记忆中间件我按使用场景说ConversationBufferMemory直接缓存所有历史消息适合短对话缺点是会快速增长。ConversationSummaryMemory用模型定期总结历史内容只保留摘要省Token适合长会话。ConversationSummaryBufferMemory折中方案既保留最近的原始消息又对更早的内容做摘要。下面这段代码是典型的“缓冲摘要”用法from langchain.memory import ConversationSummaryBufferMemory from langchain.chat_models import ChatOpenAI memory ConversationSummaryBufferMemory( llmChatOpenAI(modelgpt-4o), max_token_limit6000, return_messagesTrue )大概逻辑是当全部消息的Token数量超过max_token_limit时记忆组件会调用llm对最老的历史做摘要再用摘要替代原始内容。这样既能保住近几轮的细节又不会让上下文无限膨胀。使用记忆中间件时要注意Agent场景下记忆不只是“存历史”还要把记忆和工具调用结果分开。建议给记忆打标签或者分区存储避免把工具返回的大段JSON混入对话历史导致模型判断混乱。2.4 工具中间件把外部能力封装给模型调用工具Tools是Agent区别于普通聊天模型的关键。LangChain内置了大量工具比如各类搜索接口、数据库查询接口等但实际项目里更多是自己写函数然后包装成工具。而这恰恰是最能体现“中间件”价值的地方。用tool装饰器封装一个订单状态查询函数from langchain.tools import tool tool def get_order_status(order_id: str) - str: 根据订单号查询订单的当前状态。返回发货时间、物流节点等信息。 # 这里写真实的业务查询逻辑 return f订单{order_id}已发货当前在运输中预计明天送达。装饰器会自动读取函数的参数列表、类型、文档字符串生成一个结构化的工具描述。模型拿到这个描述就知道“哦有一个get_order_status函数参数是字符串类型的order_id可以查订单状态。”然后在需要时发出调用指令LangChain执行工具并把结果返回给模型。实战里的一个关键点是文档字符串不能乱写。工具描述是模型选择工具的主要依据描述含糊会导致模型根本不知道该调用谁。建议每个工具描述都明确写明“什么时候用”“参数是什么含义”“返回什么结果”。2.5 回调与观测中间件偷看Agent的思考过程中间件里最容易被忽略的是回调。调试Agent时如果你只看到最终输出一旦出错根本不知道是哪一步出了问题。回调机制相当于给Agent装了一整套监控仪表。LangChain内置了BaseCallbackHandler你可以在不同阶段挂上处理函数from langchain.callbacks.base import BaseCallbackHandler class DebugHandler(BaseCallbackHandler): def on_llm_start(self, serialized, prompts, **kwargs): print(模型开始推理提示词, prompts) def on_tool_start(self, serialized, input_str, **kwargs): print(调用工具输入, input_str) def on_tool_end(self, output, **kwargs): print(工具返回, output)把DebugHandler实例传给AgentExecutor的callbacks参数就能实时打印每一步动作。我第一次排查Agent循环问题时就是靠这个定位到模型反复调用同一个查询工具因为没有把“结果已拿到”写进上下文。看到日志后问题一分钟就定位了。3. 手把手实现一个带全套中间件的客服Agent3.1 场景设计与选型为了让你直观看明白这些中间件怎么协同工作我做一个智能客服Agent。场景是这样的用户问某个订单的状态Agent能调用订单查询工具能记住用户之前聊过的内容并且最终输出格式化的意图和答复。我的中间件选型如下提示模板ChatPromptTemplate负责系统指令和变量注入。输出解析PydanticOutputParser把最终回答解析成AgentReply对象。记忆ConversationSummaryBufferMemory既保留近期对话又压缩更早历史。工具tool装饰器包装一个查询函数。回调自定义Handler打印运行日志。这种组合方式在中小型业务系统里非常通用每一步都是LangChain内置能力不需要自己造轮子。3.2 代码实现与逐段讲解先准备好所有依赖和初始化from langchain.agents import AgentExecutor, create_openai_functions_agent from langchain.chat_models import ChatOpenAI from langchain.memory import ConversationSummaryBufferMemory from langchain.output_parsers import PydanticOutputParser from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.tools import tool from pydantic import BaseModel, Field class AgentReply(BaseModel): answer: str Field(description面向用户的最终回答) order_id: str | None Field(defaultNone, description本次涉及的订单号没有则为null) parser PydanticOutputParser(pydantic_objectAgentReply)接着定义Prompt模板。这里特别加入了MessagesPlaceholder用于给AgentExecutor插入历史对话和中间步骤prompt ChatPromptTemplate.from_messages([ (system, 你是某店铺的客服Agent。请根据工具返回结果回答用户问题。 最终回答必须按以下格式返回\n{format_instructions}), MessagesPlaceholder(variable_namechat_history), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ]).partial(format_instructionsparser.get_format_instructions())agent_scratchpad是LangChain内部约定给Agent保存“想法、动作、观察”的临时空间。这里不建议随意改名。然后定义工具和记忆tool def get_order_status(order_id: str) - str: 根据订单号查询订单状态包含发货和物流信息。 # 模拟查询 return f订单{order_id}状态为运输中预计明天送达 memory ConversationSummaryBufferMemory( llmChatOpenAI(modelgpt-4o), max_token_limit6000, return_messagesTrue )最后组装Agent并执行llm ChatOpenAI(modelgpt-4o, temperature0) agent create_openai_functions_agent( llmllm, tools[get_order_status], promptprompt, ) executor AgentExecutor( agentagent, tools[get_order_status], memorymemory, max_iterations3, handle_parsing_errorsTrue, verboseFalse, )这里重点说明AgentExecutor的几个关键参数。max_iterations限制最大推理循环次数防止模型反复思考不收敛。handle_parsing_errorsTrue表示当模型输出无法解析时允许把异常信息返回给模型让模型自我修正。这是个很实用的容错设计。3.3 运行效果与分析顺序执行两个问题看看记忆中间件是否生效response executor.invoke({input: 帮我查一下订单A1001的状态}) print(response[output]) response2 executor.invoke({input: 这个订单什么时候能到}) print(response2[output])第一轮调用工具返回运输中模型生成答复。第二轮虽然用户没提订单号但记忆中间件保留了历史记录里的“订单A1001”模型能自动关联上文回复“预计明天送达”。如果没有记忆这轮铁定要用户再补一次订单号。这整套代码里提示模板负责约束模型的输出格式输出解析器把回复转成结构化对象工具封装了业务能力记忆串联多轮上下文。五个中间件各司其职缺哪一个整个闭环都有断点。4. 常见问题与排查技巧实录4.1 输出解析频繁失败的三种原因我在实际项目中遇到过不少解析错误绝大多数是这三类第一Prompt里没有明确贴出格式要求。很多人只给了parser.get_format_instructions()却没跟模型强调“必须严格遵守不能输出额外文字”。建议在System指令里加一句“只能输出JSON不要返回解释”。第二字段描述写得模糊。比如把order_id描述成“订单信息”模型可能输出对象而不是字符串。字段描述要具体到格式和取值范围。第三工具返回内容干扰了模型。如果工具返回一长串格式不规则的文本模型在组织回答时容易跑偏。解决办法是在工具描述里声明“返回纯文本不需要客户看到内部格式”。4.2 记忆混乱和Token超限怎么办记忆组件不是存得越多越好。ConversationSummaryBufferMemory虽然会自动压缩但压缩时依赖LLM做摘要如果摘要模型的上下文长度不够反而会丢关键信息。排查技巧是查看记忆中间件最终注入到Prompt的消息内容。我一般会在回调Handler里打印chat_history看注入的是原始消息还是摘要判断是否出了问题。另外如果业务允许最简单的策略是给Agent直接限定单轮对话轮数超过后就提示用户重新开始这对很多客服场景完全够用。4.3 工具调用循环和死循环怎么破一个经典故障场景模型调用查询工具后拿到结果却说“还需要进一步查询”于是又调用一次如此反复直到超时。这通常是因为模型没有从工具结果中提取到关键信息或者Prompt没告诉它“拿到结果后就生成最终回答”。解决思路有三个层面降低max_iterations这是兜底在System指令里明确“工具结果包含所需信息时必须停止推理”检查工具返回内容是否过于冗长模型可能在其中找不到重点。我曾在代码里让工具只返回“已发货”而不是大段物流轨迹循环问题立刻少了很多。4.4 额外建议与最佳实践用内置中间件时有几条比较通用的经验场景建议多业务线复用把Prompt模板、工具列表固化成配置不同业务传不同参数生产环境上线一定要接入回调日志记录每次LLM调用和工具调用的耗时、结果解析结果不稳定对关键字段写校验逻辑不满足条件就强制走人工兜底记忆数据敏感不要把所有对话都塞进记忆先做脱敏和过滤这些建议都是从踩坑里总结出来的尤其第二条没有日志的Agent项目出了问题只能靠猜。最后再分享一个小技巧如果你刚开始搭Agent先别急着加知识库、加复杂路由老老实实用LangChain内置的这套中间件把“提示模板 输出解析 记忆 工具 回调”的闭环跑通。等闭环稳定了再往里加场景。我个人在实际调试中还有一个习惯任何一次Agent行为异常先开Handler看日志再精简Prompt最后才怀疑模型能力。多数问题其实都出在中间件配置和Prompt设计上模型本身比我们想象的更靠谱。这套经验在我经历的好几个项目中都被反复验证过。