LangGraph 调试指南：Graph 执行轨迹怎么看，问题怎么快速定位

很多同学第一次把 LangGraph Agent 推上生产跑了一周突然接到反馈「你那个 AI 有时候会卡死有时候答非所问」。打开控制台日志一看只有一行请求进来、一行回复出去中间那几十次 LLM 调用、工具调用、状态流转全是黑盒。你根本不知道Agent 走了哪条分支LLM 在某个节点拿到的 Prompt 是什么工具调用成功了没有哪一步状态数据搞坏了靠console.log打日志有意义但 Graph 一复杂你不知道往哪打。靠猜靠猜是要翻车的。这篇把调试 LangGraph 的完整工具链讲清楚从本地快速定位到 LangSmith 生产级追踪从看懂执行轨迹到还原「事故现场」——一套打法搞定。01 执行轨迹的本质Graph 到底把什么信息藏着了一个 LangGraph Graph 运行一次内部发生的事情可以抽象成这样一棵树节点名称走了哪个分支planner → executor还是走了 tools输入 State进入节点时的完整状态输出 Patch这个节点改了哪些字段注意是增量不是全量耗时哪个节点是性能瓶颈但默认的invoke()调用只给你最终结果中间那些全被吃掉了。要「看见」执行轨迹有两种路径本地调试stream streamEvents和云端追踪LangSmith。调试工具选型一览工具适用场景信息粒度能否事后查stream()本地开发看节点粒度节点输入/输出❌streamEvents()本地开发看 LLM 调用细节LLM Prompt/Token/工具调用❌LangSmith生产环境事后回溯全链路含 Prompt 原文✅Checkpoint History有持久化时时间旅行每步完整 State 快照✅02 本地调试stream streamEvents 双剑合璧LangGraph 的stream()不只是给流式输出用的它是「执行轨迹的可观测接口」。stream()有两种模式streamMode: values每个 chunk 是当前完整 State调试推荐和streamMode: updates默认每个 chunk 只有当前节点输出的增量 Patch生产省流量。下面这个完整示例把 Graph 搭建、stream 调试、路由决策日志全部整合在一起importStateGraphAnnotationSTARTENDfromlangchain/langgraphimportChatOpenAIfromlangchain/openaiimportHumanMessageBaseMessagefromlangchain/core/messagesimportfromlangchain/core/toolsimportToolNodefromlangchain/langgraph/prebuiltimportfromzodconstChatStateAnnotationRootmessagesAnnotationBaseMessagereducerconsttoolasyncquerystring搜索结果${query} 的相关数据namesearchdescription搜索最新信息schemaobjectquerystringconstconstnewChatOpenAImodelgpt-4o-minibindTools// ⚠️ 路由函数最容易出问题的地方每次路由都打印决策依据// 条件边走错了不报错会静默跑偏必须主动把依据打出来functionshouldContinuestate: typeof ChatState.StatetoolstypeofENDconstmessagesmessageslength1consttool_callsinArrayisArraytool_callstool_callslength0consolelog 路由 → type: ${lastMessage._getType()}, hasToolCalls: ${hasToolCalls}ifconsolelog tool_calls:JSONstringifytool_callsnull2returntoolsreturnENDconstnewStateGraphChatStateaddNodeagentasyncmessagesawaitinvokemessagesaddNodetoolsnewToolNodeaddEdgeSTARTagentaddConditionalEdgesagenttoolsENDaddEdgetoolsagentcompile// 用 stream 替代 invoke每个节点执行完都会 yield 一次// streamMode: values → 每个 chunk 是当前完整 State调试推荐一眼看全量// streamMode: updates → 默认每个 chunk 只有这步的 Patch生产省流量forawaitconstofawaitstreammessagesnewHumanMessage帮我搜一下Q1销售数据streamModevaluesconstmessageslength0constmessages1consolelog\n✅ State 更新 | messages: ${msgCount}条 | 最新: ${lastMsg?.content?.toString().slice(0, 80)}运行后你会看到每个节点执行完后当前的完整 State 是什么路由函数每次决策时走了哪条边工具调用了没有。这比单纯看最终结果直观十倍。03 streamEvents看穿 LLM 调用的黑盒光看节点粒度不够。80% 的问题出在节点内部——Prompt 传错了Tool Call 没触发streamEvents把节点内部每一次 LLM 调用的入参和出参全都暴露出来// streamEvents 的 version 必须写 v2forawaitconstofstreamEventsmessagesnewHumanMessage帮我分析销售数据versionv2// LLM 调用开始这里能看到完整 Prompt是调试的第一个切入点// LLM 回答不对时先看这里——80% 是 Prompt 构建有 bug不是模型的问题ifeventon_chat_model_startconsolelog\n [${event.metadata?.langgraph_node}] LLM 调用开始consolelog 完整 Prompt:JSONstringifydatainputmessagesslice2null2// LLM 调用结束看回复内容和 Token 消耗ifeventon_chat_model_endconstdataoutputusage_metadataconsolelog LLM 调用结束 | 回复: ${event.data.output.content?.toString().slice(0, 100)}consolelog Token: prompt${usage?.input_tokens} completion${usage?.output_tokens}// 工具调用入参和结果ifeventon_tool_startconsolelog\n 工具 [${event.name}] 调用入参:JSONstringifydatainputifeventon_tool_endconsolelog✅ 工具 [${event.name}] 结果:dataoutput关键事件类型速查事件名触发时机最有用的字段on_chat_model_startLLM 调用前data.input.messages完整 Prompton_chat_model_endLLM 调用后data.output.content、usage_metadataon_tool_start工具调用前name、data.inputon_tool_end工具调用后data.outputon_chain_start节点开始metadata.langgraph_node节点名排查「答非所问」的标准动作先开streamEvents找到对应节点的on_chat_model_start把完整 Prompt 打印出来看绝大多数情况问题就在那里。04 LangSmith生产环境的「飞行记录仪」本地调试靠 console.log 够用。但生产环境有个致命问题你不可能一直盯着日志用户遇到问题时你已经不在场了。LangSmith 是 LangChain 官方的追踪服务原理是Graph 运行时每一步都被自动上报保存出问题了打开后台回放。接入方式// ─── 第一步.env 文件加 4 个变量代码零改动 ───// LANGCHAIN_TRACING_V2true// LANGCHAIN_API_KEYyour-key # smith.langchain.com 获取// LANGCHAIN_PROJECTmy-agent-prod # 建议按 dev/prod 分组// OPENAI_API_KEYyour-openai-key// ⚠️ 关键坑dotenv.config() 必须在所有 LangChain import 之前// LangChain 初始化时会读取 env如果 dotenv 在后面加载就晚了importasfromdotenvconfig// 第一行importChatOpenAIfromlangchain/openai// 之后再 import// ─── 第二步调用时加 metadata 和 tags方便事后检索 ───constawaitinvokemessagesnewHumanMessageconfigurablethread_idmetadatauser_id// 方便按用户筛选找「用户xxx投诉的那次」session_id// 方便按会话筛选environmentproduction// 区分 dev/prodtagsproductionagent-v2// ─── LangSmith Trace 树结构后台看到的样子───// Graph Run (root)// ├── agent第一次// │ └── ChatOpenAI// │ ├── Input: { messages: [用户输入] } ← 完整 Prompt 在这里// │ └── Output: { tool_calls: [search] }// ├── tools → search → 结果返回// └── agent第二次// └── ChatOpenAI// └── Output: { content: 根据数据分析... }//// 定位问题三步法// 1. 用 user_id/session_id 找到那次出问题的 run// 2. 展开 Trace 树找第一个红色失败或异常耗时节点// 3. 点进去看 LLM 的输入 PromptLangSmith 没数据八成是 dotenv 加载顺序错了——dotenv.config()放在 LangChain import 之后LangChain 初始化时还没读到 envLangSmith 没被激活。另一种常见情况LANGCHAIN_PROJECT留空数据全堆进 “default”找起来很混乱。建议用my-agent-dev/my-agent-prod明确命名。05 Checkpoint 调试时间旅行还原「事故现场」如果 Graph 用了 Checkpoint你还有超强调试能力从任意历史节点重新执行。生产场景用户聊了 20 轮第 15 轮出错了总不能让他重来。找到出错前的 checkpoint修复 State从那里继续跑。importMemorySaverfromlangchain/langgraphimportPostgresSaverfromlangchain/langgraph-checkpoint-postgres// ⚠️ MemorySaver 只适合本地调试生产必须用 PostgresSaver// MemorySaver 把所有 checkpoint 存内存长时间跑必然撑爆constnewMemorySaver// 生产环境替换为// const checkpointer PostgresSaver.fromConnString(process.env.DATABASE_URL!);// await checkpointer.setup(); // 首次运行建表constcompileconstconfigurablethread_iddebug-session-001// 跑一次产生 checkpoint 历史awaitinvokemessagesnewHumanMessage帮我分析一下销售数据// 查看这个 thread 的全部 checkpoint按时间倒序forawaitconstofgetStateHistoryconsolelogstep: ${snapshot.metadata?.step}| next: ${snapshot.next}| messages: ${snapshot.values.messages?.length}条| checkpoint_id: ${snapshot.config?.configurable?.checkpoint_id}// 从某个 checkpoint 重新执行// 拿上面打印的 checkpoint_id填进去就能精确「回滚到那一刻」重新调试constawaitinvokenullconfigurablethread_iddebug-session-001checkpoint_id填入目标 checkpoint_idconsolelog从断点恢复结果:getStateHistory给你每个节点之间的完整 State 快照。找到出问题的那步拿 checkpoint_id精确「回滚到那一刻」重新调试。06 常见坑调试本身也有陷阱坑1stream 模式没看清楚。updates默认只有 Patchvalues才是全量 State。调试时务必传{ streamMode: values }否则看到的 chunk 只有变化的字段不是完整状态。坑2LangSmith 没数据。九成九是 dotenv 加载顺序问题见第 04 章。dotenv.config()必须在所有 LangChain import 之前这是最常见的接入坑。坑3MemorySaver 线上跑内存炸了。MemorySaver只适合本地生产必须切PostgresSaver见第 05 章代码示例。坑4streamEvents 里metadata.langgraph_node为空。原因是 LLM 在 Graph 外部初始化没被 Graph 上下文捕获。解决方法把 LLM 调用移到节点函数内部执行或确保所有 LLM 调用都在 Graph 的invoke/stream上下文链路上。坑5全量 LangSmith 追踪费用暴涨。用采样率控制只追踪 10% 的请求设置if (Math.random() 0.1) process.env.LANGCHAIN_TRACING_V2 true; else delete process.env.LANGCHAIN_TRACING_V2;或者只在 catch 块里开启追踪发生错误才上报。总结这篇把 LangGraph 调试从本地到生产的完整链路走了一遍stream()用streamMode: values是本地调试的起点每个节点执行后能看到全量 State比updates模式直观得多不用自己拼增量 Patch。streamEvents()是看清 LLM 黑盒的唯一方式on_chat_model_start里的完整 Prompt 是定位「答非所问」问题的第一个切入点80% 的问题就藏在这里。路由函数里加决策日志是调试条件路由的最快路径条件边走错了不报错只会静默跑偏必须主动把路由依据打出来。LangSmith 是生产环境的飞行记录仪4 个 env var 零侵入接入dotenv 加载顺序是最常见接入坑user_id session_id是事后定位问题的关键标签。Checkpoint 时间旅行是高阶调试能力找到出错前的 checkpoint_id修复 State从那里重跑生产环境必须用 PostgresSaver 替换 MemorySaver否则必内存溢出。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】