1. 别急着敲代码先弄清 LangChain 在 Agent 里到底干了什么去年我在做一个内部工具的时候第一次认真用 LangChain起因很朴素产品那边想要一个能自己判断这个问题该去查文档还是该去翻数据库的助手而我之前手写的那套 if-else 路由已经膨胀到没人敢动。那段时间我搜了不少 Agent 开发学习路线的资料发现大部分教程上来就是装包、调接口、跑通 Demo但真正卡人的地方从来不是这几步而是搞不清框架到底替你屏蔽了什么、又在哪些地方给你挖了坑。这篇笔记就是把这个过程完整记下来适合已经会写 Python、调过大模型接口但还没系统性接触过智能体开发的同学。1.1 直接调模型接口缺的到底是哪几块拼图很多人第一次接触 Agent会觉得它跟调个接口拿段文字没什么本质区别。我一开始也是这么想的直到把需求摊开看才发现问题。你要让模型完成一件稍微复杂的事至少缺四样东西。第一样是结构化输入的组织方式。系统提示、用户输入、历史对话、检索回来的资料、工具返回的结果这些东西得按模型能理解的顺序拼成一个消息序列。手写字符串拼接能跑通一次但一旦要动态插入历史和工具结果字符串就会变成一团谁也读不懂的泥巴。第二样是外部能力的接入。模型本身只会生成文本它没法查数据库、没法发请求、没法读你本地的文件。你得把能做什么包装成模型可以理解和调用的形式同时还要给出参数说明和返回值。第三样是决策循环。如果任务需要多步才能完成比如先查资料再总结再校对那模型执行完一步之后要知道下一步该干什么什么时候算结束。这个循环的控制逻辑如果不抽出来会散落在业务代码的各个角落。第四样是过程可观测。Agent 跟普通函数调用最大的区别是它的路径不可预测同一句话可能走三条不同的工具链。出问题的时候你需要知道它调了哪个工具、传了什么参数、拿回了什么否则排查基本靠猜。LangChain 的价值就在于把上面这四件事各抽了一层抽象出来Prompt 模板对应第一样Tool 抽象对应第二样Agent 与 AgentExecutor 对应第三样Callback 机制对应第四样。它没有让模型变聪明只是把重复劳动标准化了。认清这一点很重要因为后面遇到各种莫名其妙的报错时你会知道该去哪一层找原因。1.2 三层抽象Model、Prompt、Output Parser 的分工LangChain 的基础抽象其实就三层我把它们用一句话概括Model 负责跟模型说话Prompt 负责准备要说的话Output Parser 负责把回话翻译成程序能用的结构。Model 这一层主要解决的是换模型不改业务代码的问题。它提供了invoke、stream、batch三种调用方式其中stream对流式输出特别友好batch适合批量离线处理。你写业务逻辑的时候只依赖BaseChatModel接口要换供应商的时候只需要改实例化的那一行。Prompt 这一层容易被低估。表面上它只是字符串模板实际上它承担了变量注入和消息角色划分两件事。ChatPromptTemplate允许你把 system、human、ai 三种角色的消息分开组织再通过MessagesPlaceholder动态插入历史对话或者中间步骤。这个设计在 Agent 场景下非常关键因为 ReAct 风格的提示词需要在固定位置插入思考-行动-观察的循环记录手拼字符串几乎不可能维护。Output Parser 是把自然语言变成结构化数据的桥梁。最常用的是 Pydantic 解析器你定义一个数据类描述想要的字段解析器负责在提示词里加上格式说明再把模型返回的文本还原成对象。这里有个经验要提醒解析失败率跟模型能力、字段复杂度、字段数量都强相关字段超过五六个之后失败率会明显上升我一般会把复杂结构拆成两三次调用来做。三层抽象各管一段组合起来才是一个完整的链。这个链的概念是所有后续内容的基础包括 Agent 本身本质上也是一条被循环执行、路径由模型决定的链。1.3 Chain 和 Agent 的分水岭谁在做决定这是新手最容易混淆的一点。Chain 和 Agent 长得像都是把多个组件串起来但它们的控制流归属完全不同。Chain 的执行路径是写死的。你先做检索再把检索结果塞进提示词再调模型再解析输出顺序是你定的模型只是中间的一环。哪怕用 LCEL 的管道语法写本质没变只是写法更紧凑。Agent 的执行路径是模型定的。你告诉它有哪些工具可用它自己判断该调哪个、调几次、什么时候停下来。你写的那套循环逻辑只负责给模型机会决策和把结果喂回去至于走哪条路你事先不知道。这个区别带来的连锁反应很大。Chain 的测试是确定性的输入固定输出就固定Agent 的测试必须考虑路径同一个问题可能这次用两步解决下次用四步。Chain 的调试看的是数据流Agent 的调试看的是决策轨迹。很多人第一次写 Agent 失败就是因为还在用 Chain 的思维去设计它——试图把每一步都控制死结果模型在该自由发挥的地方被提示词捆住了手脚在不该自由发挥的地方又乱来。我的建议是能用 Chain 解决的场景就别上 Agent。如果你的业务逻辑是固定的检索加总结就是检索加总结那 Chain 更快、更稳、更便宜。Agent 真正的用武之地是那些步骤数量不确定、工具选择依赖中间结果的场景比如开放式问答、多源信息汇总、带条件分支的任务执行。搞清楚这个边界能省掉很多无谓的调试时间。2. 把一套能长期用的开发骨架搭起来环境这一步看似简单但我见过太多人卡在这包括我自己第一次配的时候。问题不在于命令有多难而在于这个生态的包依赖关系比较绕版本不匹配会导致一堆看不懂的报错。2.1 依赖安装分清哪个包该装哪个LangChain 在 0.1 版本之后做了模块拆分现在你至少要知道这几个包的区别。包名职责是否必装langchain-core基础抽象模型接口、提示模板、工具基类、运行时是作为依赖自动装langchain高层编排Agent、Chain 的具体实现是langchain-community社区维护的第三方集成向量库、加载器等按需langchain-openai具体模型供应商适配按需langgraph有状态图编排后面进阶会用暂时可不装很多人第一次pip install langchain之后发现代码里from langchain_openai import ChatOpenAI报错就是因为供应商适配包是拆出去的得单独装。这个坑几乎人人踩过一次。我自己的习惯是先建虚拟环境再固定大版本号安装python -m venv .venv source .venv/bin/activate pip install langchain0.3,0.4 langchain-openai0.2 python-dotenv固定大版本这一步很关键。LangChain 的小版本迭代速度很快很多 API 的签名在不同小版本之间有细微差别不锁版本的话过两周再跑同一份代码可能就报错了。我在一个项目里吃过这个亏当时没锁版本CI 上跑得好好的本地重装依赖之后直接崩查了半天才发现是某个参数默认值变了。2.2 密钥管理和模型选择别把 Key 写进代码密钥管理这事没必要展开太多但有两句话必须说。第一绝对不要把密钥硬编码在代码里哪怕是内部项目因为代码迟早会进版本库。第二用.env加python-dotenv的方式就够用了没必要上什么复杂的密钥管理服务。import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() def build_model(temperature: float 0.0) - ChatOpenAI: return ChatOpenAI( modelos.getenv(MODEL_NAME, gpt-4o-mini), temperaturetemperature, timeout60, max_retries2, )这里temperature设成 0 是 Agent 场景下的常规做法。原因很直接Agent 每一步都要做决策随机性会让同样的输入产生不同的工具选择调试的时候你会疯掉。不过在生成最终答案的那一步可以适当调到 0.3 到 0.5让措辞自然一些。max_retries建议打开网络抖动导致的失败没必要让用户重试。另外提醒一句不同模型对工具调用的支持程度差别很大。支持原生 function calling 的模型工具选择准确率明显更高而且不需要在提示词里写一大段格式说明。选模型的时候优先考虑这一点比看参数规模有用得多。2.3 第一个能跑的 Agent从工具定义开始我不建议一上来就写最复杂的版本。先定义两个工具一个做检索一个做计算然后跑通最小闭环这是我自己摸索出来最高效的路径。from langchain_core.tools import tool tool def search_docs(query: str) - str: 在内部知识库中检索与 query 相关的文档片段。 当问题涉及内部流程、产品规范、历史决策时使用本工具。 输入应当是一句完整的自然语言描述不要只给一两个关键词 否则检索质量会明显下降。 # 伪代码实际替换成你的检索实现 hits retriever.search(query, top_k4) return \n\n.join(h[text] for h in hits) tool def calc(expression: str) - str: 计算一个算术表达式例如 128 * 1.06。 只在需要精确数值结果时使用表达式必须是合法的 Python 算术语法。 allowed set(0123456789-*/(). ) if not set(expression) allowed: return 表达式包含不允许的字符请只使用数字和四则运算符。 return str(eval(expression, {__builtins__: {}}, {}))重点看tool装饰器下面的那段 docstring。这段文字不是给人看的是给模型看的它直接决定模型会不会、以及在什么情况下选择这个工具。我见过的大部分工具选不对问题根因都在这里。描述里至少要包含三样东西这个工具做什么、什么时候该用、输入应该长什么样。写得越具体模型的判断越准。有了工具之后组装 Agent 的代码其实很短from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.agents import AgentExecutor, create_tool_calling_agent prompt ChatPromptTemplate.from_messages([ (system, 你是一个严谨的助手。需要外部信息时调用工具 不要凭空编造。无法确定时明确说明。), (human, {input}), MessagesPlaceholder(agent_scratchpad), ]) tools [search_docs, calc] agent create_tool_calling_agent(build_model(), tools, prompt) executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations6, handle_parsing_errorsTrue, ) result executor.invoke({input: 我们的退款流程是几天内到账如果是 128 元的订单手续费按 6% 算实际扣多少}) print(result[output])这几个参数我逐个说下理由。verboseTrue在开发阶段一定要开它会把每一步的思考和工具调用打印出来这是你唯一的观察窗口。max_iterations6是防御性的防止模型陷入循环六步对大多数任务够用了。handle_parsing_errorsTrue能让解析失败时把错误信息回传给模型让它自己修正而不是直接抛出异常中断整个流程。MessagesPlaceholder(agent_scratchpad)这行是必须的它的位置是模型写中间过程的地方。少了它Agent 会报提示词变量缺失的错误这也是最常见的入门报错之一。3. ReAct 循环一次提问背后到底发生了什么跑通了不代表理解了。我强烈建议在跑通之后做一件事把verbose的输出逐行拆开看一遍搞清楚每一步的数据流向。这部分看不懂后面所有调试都是盲猜。3.1 提示词被动态拼成了什么样当executor.invoke被调用的时候LangChain 做的事情比你想的多。它把系统提示、用户输入、工具的参数描述全部拼成一段长长的消息序列发给模型同时在结尾插入一个特殊的标记告诉模型现在轮到你决定下一步。如果用 ReAct 风格的提示词不支持原生工具调用的模型会走这条路模型被要求按固定格式输出Thought: 我需要先查一下退款流程 Action: search_docs Action Input: 退款到账时间 Observation: 退款一般在 3-7 个工作日到账... Thought: 还需要确认手续费规则 Action: search_docs Action Input: 订单手续费比例 Observation: ... Thought: 现在可以做计算了 Action: calc Action Input: 128 * 0.06 Observation: 7.68 Thought: 我已经知道答案了 Final Answer: 退款一般 3-7 个工作日到账...框架会解析这段文本提取出 Action 和 Action Input执行对应的 Python 函数把返回值作为 Observation 追加进agent_scratchpad然后重新调用模型。循环往复直到模型输出Final Answer或者达到迭代上限。用create_tool_calling_agent的时候这个格式约定从提示词转移到了模型的工具调用协议里你看到的日志会不一样但底层逻辑完全相同决策、执行、回填、再决策。3.2 循环的终止条件和几个容易踩的边界终止条件表面上看只有一个模型输出了最终答案。但实际运行中停止的原因至少有四种分清楚它们对排错非常关键。第一种是正常结束模型给出了 Final Answer这是最理想的。第二种是达到max_iterations框架强制中断返回的 output 可能是空的或者一段半成品。第三种是模型输出的格式无法解析如果没开handle_parsing_errors这时候会直接抛异常开了之后框架会把解析错误当作一次 Observation 回传给模型。第四种是工具本身抛异常默认情况下这也会中断流程除非工具内部自己做了兜底。我用表格整理一下这几种情况的处理思路停止原因典型日志特征处理方式正常结束出现 Final Answer无需处理迭代超限日志末尾无 Final Answer步骤数等于上限提高上限或优化提示词减少绕路格式解析失败日志中提示 could not parse开启容错同时简化提示词格式要求工具执行报错日志中抛出具体异常工具内部做 try/except返回可读的错误说明这里有个经验值得单独说工具内部抛异常时返回可读的错误信息比让异常往上冒更有用。因为模型看到查询超时请稍后重试或者换一种问法这种文字它有可能自己调整策略而看到 Python 的堆栈它基本只会把错误原样复述一遍。3.3 用 Callback 把中间过程抓出来verboseTrue适合开发时肉眼观察但如果你想把轨迹记录下来做后续分析就得用 Callback。写一个最简单的处理器就能看到很多信息from langchain_core.callbacks import BaseCallbackHandler class TracePrinter(BaseCallbackHandler): def on_tool_start(self, serialized, input_str, **kwargs): print(f[tool-start] {serialized.get(name)} args{input_str}) def on_tool_end(self, output, **kwargs): text str(output).replace(\n, )[:200] print(f[tool-end] - {text}) def on_tool_error(self, error, **kwargs): print(f[tool-error] {type(error).__name__}: {error}) result executor.invoke( {input: 退款要几天}, config{callbacks: [TracePrinter()]}, )on_tool_error这个回调特别实用很多人不知道它的存在遇到工具报错只能靠猜。把它接上之后哪一步出的问题一目了然。再往前走一步你可以把这些事件按会话 ID 落到本地文件里形成一份可回溯的轨迹日志。我在一个项目里就是这么做的后来排查一个偶发的错误时直接翻日志对比了三次失败和五次成功的路径差异五分钟定位到问题是某个工具在特定参数下返回了空字符串导致模型误判成查不到。这种问题不靠轨迹日志基本没法查。4. 我踩过的几个坑每个都耗掉过半天这部分是我写这篇笔记最主要的原因。文档里不会写这些但它们确实会消耗掉你大量时间。4.1 工具描述写得太随意模型永远选错最典型的表现是你明明只想让它查资料它偏偏去调计算工具或者两个工具功能相近时它总是选你不想要的那个。根因几乎总是在描述上。我当时的两个工具描述分别写的是搜索和计算看起来清楚但对模型来说信息量太少了——搜索什么在哪搜什么时候该搜这些都没说。后来我把描述改成了前面 2.3 节那样的三段式结构命中率立刻上来了。还有个细节容易被忽略工具数量超过七八个之后选择准确率会下降。这不是描述的问题是模型在大量选项中做判断本身就容易出错。解决办法是分组或者先用一次调用让模型判断这属于哪一类问题再在对应的子工具集里选。4.2 循环停不下来迭代上限和提示词都要管有一次我遇到 Agent 一直重复调同一个工具六七步之后被强制中断输出的答案还是半成品。翻日志发现它每次都把同一个查询重新发一遍因为工具返回的结果确实没包含它想找的信息而它不知道该怎么办。这里有两个层面的问题。一是工具的返回值必须足够有信息量包括没找到这个结论本身也要明确表达比如返回未检索到相关内容建议换用更宽泛的关键词而不是返回空字符串或者一个空的列表字符串。二是提示词里要给出明确的退出指引比如加上如果连续两次检索都没有获得有用信息应当直接说明无法回答而不是继续尝试。迭代上限那里六步到八步是个比较合理的区间。设太低会导致复杂任务做不完设太高会让偶发的死循环拖很久还白烧 token。4.3 多轮对话记忆接错了位置Agent 加记忆这件事最坑的地方在于接在哪一层。如果你把记忆接在 Executor 外面也就是每次调用前手动把历史塞进input那模型会看到一大段拼接的文本效果不稳定。正确的做法是让记忆以消息列表的形式进入提示词用MessagesPlaceholder占位让每条历史保持独立的消息角色。LangChain 现在推荐的方式是RunnableWithMessageHistory加一个会话存储from langchain_core.runnables.history import RunnableWithMessageHistory from langchain_community.chat_message_histories import ChatMessageHistory store {} def get_history(session_id: str): if session_id not in store: store[session_id] ChatMessageHistory() return store[session_id] conversational RunnableWithMessageHistory( executor, get_history, input_messages_keyinput, history_messages_keychat_history, ) conversational.invoke( {input: 那如果订单是 200 元呢}, config{configurable: {session_id: user-42}}, )注意这里提示词模板里要额外加一个MessagesPlaceholder(chat_history)位置放在 system 之后、当前用户输入之前。漏了这一步历史就进不去表现出来就是它完全忘了刚才说过什么。另一个坑是历史越长成本和延迟越高而且早期信息会稀释当前意图。我一般会在历史超过十几轮之后做摘要压缩把早期对话压成一段简短描述保留最近几轮原文。4.4 结构化输出解析失败率比想象中高如果你让 Agent 或某个步骤输出 JSON然后交给下游程序处理那你会很快遇到解析失败。常见原因有三个模型在 JSON 外面加了说明文字、字段类型不符合预期、嵌套层级太深。我的处理顺序是这样的先给模型一个明确的示例输出比单纯描述字段更有用然后用 Pydantic 定义模型并开启校验最后再加一层重试逻辑把解析错误原文回传给模型让它重新生成。这三层叠上去之后失败率能压到很低。但更根本的建议是别让模型一次性输出复杂嵌套结构。拆成两三次简单调用每次只输出一层整体稳定性反而更高因为失败重试的成本也低。4.5 版本升级带来的破坏性变更这个坑没有技术含量但杀伤力最大。LangChain 从 0.1 到 0.3 的过程中Agent 相关 API 改动相当频繁很多网上搜到的示例代码已经跑不通了。我的应对办法很简单任何一份示例代码先看它的版本号对不上就只借鉴思路别直接抄。同时在自己的项目里锁死大版本升级之前先在分支上跑一遍全部测试用例。另外官方文档的版本切换器要用起来看新版本对应的写法能省掉大量试错。5. LangChain 和 LangGraph 的边界在哪什么时候该换搜langchain 和 langgraph 的区别的人非常多说明大家在这一点上普遍困惑。我的看法是它们不是替代关系解决的是不同复杂度的问题。5.1 一个是单轮决策循环一个是有状态的图AgentExecutor的结构很简单一个循环每轮让模型决策执行工具回填结果直到结束。它很适合给一个问题、调用若干工具、给一个答案这类场景。但有些需求它天生做不好。比如先收集信息中途要等人工审批审批通过再继续失败则回到某个中间步骤重来这种带分支、带暂停、带状态回滚的流程用 Executor 硬塞会非常别扭。LangGraph 的做法是把整个流程建模成一张有状态的图节点是处理步骤边是流转方向状态是一个可以在节点间传递和修改的字典。它能做到 Executor 做不到的几件事流程中间可以暂停并等待外部输入、状态可以持久化并在之后恢复、分支和循环的写法是显式的。检查点机制让断点续跑变成了框架内置能力而不是你自己去存数据库。一句话总结流程简单、路径由模型全权决定用 Executor流程有明确的阶段划分、需要人工介入或者需要状态持久化用 LangGraph。5.2 从 Executor 迁到图思路怎么转迁移的心法是把循环换成节点和边。原本 Executor 内部隐式做的决策现在变成图里的一个判断节点原本的工具执行变成另一个节点原本的终止条件变成一条指向结束的边。from typing import TypedDict, Annotated from langgraph.graph import StateGraph, END from langgraph.graph.message import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages] def call_model(state: AgentState): return {messages: [build_model().invoke(state[messages])]} def should_continue(state: AgentState) - str: last state[messages][-1] return tools if getattr(last, tool_calls, None) else END graph StateGraph(AgentState) graph.add_node(agent, call_model) graph.add_node(tools, tool_node) graph.set_entry_point(agent) graph.add_conditional_edges(agent, should_continue, {tools: tools, END: END}) graph.add_edge(tools, agent) app graph.compile()这段代码看起来比 Executor 长但换来的是完全透明的控制流。你能清楚地看到每一步是怎么流转的加分支、加人工审核节点都是在这个骨架上扩展不用去猜框架内部做了什么。5.3 学习顺序上的一个建议我见过两种极端的学法。一种是死磕 Executor把所有参数和边界情况都摸清楚再去看别的另一种是跳过 LangChain 直接学 LangGraph觉得前者已经过时了。两种都不太对。Executor 虽然在某些场景下被图取代但它背后那套决策-执行-回填的循环模型是所有 Agent 框架的共同基础理解了它看任何框架都能快速对上号。而跳过它直接学图很容易变成照着示例改参数遇到问题不知道问题出在哪个抽象层。我的建议是先用 Executor 跑通一个能用的 Agent把工具描述、迭代控制、记忆接入这三件事都做一遍然后再引入 LangGraph 处理那些需要显式流程控制的场景。这个顺序走下来两份知识是叠加的而不是互相干扰的。6. 把它接到一个真实的小需求上光跑 Demo 不算掌握得有一个稍微完整一点的东西。我拿内部文档问答加简单计算这个需求做过一遍流程完整但不复杂很适合当第一个练手项目。6.1 需求拆解和工具设计需求是这样的用户用自然语言提问问题可能涉及内部文档里的规定也可能需要做一点数值计算还可能两者都要。回答要标明信息来源算不对的地方不能瞎给。拆成三样东西一个检索工具负责在文档库里找相关片段一个计算工具负责精确算术一个提示词约束输出格式和引用要求。这里有个设计上的取舍值得说一下。我一开始想着做一个综合工具内部自己判断该检索还是该算。后来放弃了因为这样等于把决策逻辑藏进了代码里模型反而失去了调整的机会。把能力拆细、让模型来组合通常比做一个全能工具效果更好因为模型能看到每一步的结果并据此调整策略。另一个细节是检索工具返回的内容要带上来源标识比如文件名加片段编号。这样模型在最终答案里才可能引用用户也能去核对。如果返回的只是一堆纯文本模型想标注来源都无从下手。6.2 代码怎么组织调试怎么做我的目录结构大概是这样agent_demo/ .env config.py # 模型实例、全局参数 tools/ __init__.py retrieval.py # 检索工具 calculator.py # 计算工具 prompts.py # 提示词模板集中管理 agent.py # 组装 Executor cli.py # 命令行入口 traces/ # 轨迹日志输出目录把提示词单独放一个文件这一点我强烈推荐。提示词的迭代频率远高于代码逻辑放在一起改起来容易误伤而且不方便对比不同版本的效果。调试的时候我会准备一个小测试集大概二十来条问题分成三类只需要检索的、只需要计算的、需要两步的。每次改完提示词或工具描述就跑一遍看看命中率。这个习惯让我的调整有了依据而不是凭感觉改来改去。测试集的构造要注意覆盖边界情况比如文档里没有答案的问题这种最能暴露 Agent 会不会硬编。6.3 输出质量的评估和迭代方向跑了一段时间之后我发现问题主要集中在这几类检索工具返回的片段不够相关导致模型答非所问多步任务时模型在中间步骤就给出答案没走完流程计算结果的单位或者格式不统一。对应的调整分别是优化检索的召回参数和分块策略让片段更聚焦在提示词里明确必须完成所有必要步骤后再给出最终答案给最终输出加一个格式约束规定数值统一保留两位小数并带单位。评估这块如果没有专门的平台用最朴素的办法也行把每次调用的完整轨迹存下来人工抽查错误案例统计错误类型分布。二十条样本里能看出规律比盲目改提示词有效得多。等规模上来之后再考虑引入更系统的评估方式。最后分享一个小技巧。我在config.py里放了一个开关控制是否打印完整提示词。排查问题时把它打开你就能看到模型实际收到的内容长什么样很多模型怎么这么答的疑问看一眼提示词就明白了。这个开关帮我省下的时间比我写过的任何调试代码都多。