LangGraph实战：从LangChain迁移到状态图Agent的完整指南-北京尧图网络

单次对话很顺工具调用也正常一旦进入多轮、多分支、带条件判断的真实需求Agent就开始乱跑。这是很多人从LangChain转向LangGraph的直接原因。LangChain擅长把LLM调用变成一条链但当流程需要分岔、循环、回退、子图并行的时候链式模型就撑不住了。LangGraph用状态图重构了Agent的执行流程让每一步都由开发者定义、由状态驱动、由代码控制。这篇文章不铺开讲框架原理而是按企业级Agent落地的主线走一遍先认清LangChain和LangGraph的边界再手写一个状态图Agent接着用TextToSQL把完整流程跑通最后解决可观测和部署问题。最后你会得到一个判断LangGraph真正改变的不是“能不能调工具”而是“流程能不能被设计、被控制、被复用”。1. 先认清LangChain和LangGraph的分工再决定是否要迁移很多刚接触这套技术栈的人会问LangGraph是不是LangChain的升级版LangChain是不是要被替代了其实它们根本不是同一层的东西硬放到一起比较会得出很多错误结论。1.1 LangChain是工具箱LangGraph才是编排器LangChain更像一个工具箱。它解决的是“和LLM打交道的基础设施问题”模型封装、Prompt模板、文档加载、向量存储、工具调用规范、输出解析这些能力都很实用。尤其在做RAG、文档问答、基础工具调用时LangChain可以帮你省掉大量重复代码。LangGraph则处在更高的编排层。它提供了一个图执行框架用来表达“下一步走哪里、什么条件继续、什么条件结束”。LangGraph并不打算替代LangChain的模型封装和工具定义它甚至默认使用LangChain那套抽象来组织节点内部逻辑。用厨房来打比方LangChain是锅、铲、灶、冰箱按菜谱一步步做没问题。但如果要经营一家餐厅后厨的订单会同时来、食材会缺、出餐顺序会变你需要一张能动态分派的流程图纸——谁是主厨、谁切菜、什么情况重做、什么情况直接装盘。LangGraph提供的就是这张图纸。所以不要问LangChain和LangGraph谁更强要问自己需要什么如果只是做单次问答、检索增强、文档总结用LangChain就很顺手如果要做一个长期运行、带状态、带分支、会调多个工具的AgentLangGraph才是那层缺失的编排能力。1.2 V1 Agent最典型的三个问题不可控、无状态、难调试早期用LangChain写Agent最普遍的方式是让模型进入一个循环LLM决定调用哪个工具拿到工具结果后再喂给LLM直到模型自己认为任务完成。Demo阶段这条路跑得很顺但到了真实业务里问题会集中暴露。第一个是流程不可控。模型自行判断何时调用工具、调用几次、什么时候结束。对于使用者来说这几乎是黑盒。一旦进入错误分支Agent会沿着错误路径一直跑甚至反复调用同一个失败工具既浪费token又得不到结果。第二个是状态管理缺失。V1 Agent通常只把当前消息和最近的中间结果塞进上下文缺少对全局状态的显式管理。真实业务往往跨多个节点查数据库、清洗数据、生成报告、通知用户。每一步之间的状态流转全靠prompt硬撑prompt一长模型就开始串信息。第三个是调试困难。链式调用出错时只能看到最终输出或几行回调日志完全不知道模型是基于哪段上下文做出了某个决定。本地演示时还能凑合一旦上线用户问“为什么得到这个结果”整个链路说不清。LangGraph能很快被采用核心原因就是它把Agent从“自由发挥”变成了“按图执行”。模型仍然可以自主决策但决策范围、路径边界、结束条件都由代码定义。1.3 什么场景值得迁移什么场景建议继续用Chain从工程经验看存在明确分支和循环的流程最值得迁移。比如TextToSQLAgent要判断问题要不要查库SQL生成失败要重试SQL有风险要拦截执行出错要修正。这种流程用Chain写会堆出大量“if/else包裹LLM调用”的胶水代码用Graph表达却非常自然。另一种情况是多Agent协作或子任务复用。主Agent负责理解意图子Agent分别做查询、分析、报表或者某个子流程会被多个场景复用。Graph可以在节点粒度做封装避免把一切逻辑都堆在一个巨型prompt里。反之如果只是RAG问答、模板化总结、单工具调用建议不要迁移。保持简单。Graph带来的收益在于流程复杂化之后的控制力和可维护性没有复杂流程时它只是增加一层抽象。2. 手搓一个LangGraph Agent先把状态和边界定义清楚LangGraph和LangChain最大的认知差异在于写LangChain时你先想“调用链”写LangGraph时你先想“状态”。流程是节点和边的次级产物状态才是贯穿始终的东西。2.1 状态设计先回答“流程跑完要留下什么”在LangGraph里节点函数接收当前状态处理完后返回状态的一个增量。一张图的所有节点共享同一个状态结构。这个设计非常像前端状态管理数据往上提变化通过返回值向内传递。定义状态时先不要急着写节点而是问自己整个Agent跑完之后用户和下游系统需要拿到什么以一个最简Agent为例from typing import TypedDict, Annotated class AgentState(TypedDict): messages: list tool_calls: list final_answer: str这三个字段分别记录对话历史、工具调用记录、最终回复。看起来简单但已经能支撑一个基础ReAct流程。实际项目中状态通常会更丰富比如用户原始输入中间推理结果候选输出验证结果重试次数运行元信息trace_id、耗时、token消耗设计状态的原则是只放流程需要的东西不要试图把所有中间变量都塞进去。状态越大每个节点传参越慢调试时越难看清关键信息。2.2 节点和边把Agent拆成能维护的步骤LangGraph的核心执行单位是节点。一个节点就是一个Python函数输入是完整状态返回状态增量。节点内部可以调用LLM、执行工具、做任何业务逻辑。典型的ReAct Agent可以拆成三个节点from langgraph.graph import StateGraph, END builder StateGraph(AgentState) builder.add_node(agent, call_llm) builder.add_node(tools, run_tools) builder.add_node(respond, generate_response) builder.set_entry_point(agent) builder.add_conditional_edges( agent, should_continue, { continue: tools, end: respond } ) builder.add_edge(tools, agent) builder.add_edge(respond, END) app builder.compile()这个图的执行逻辑是入口进入agent节点LLM判断下一步。如果LLM决定调用工具走tools节点执行执行完后回到agent让LLM看到工具结果。如果LLM认为信息足够进入respond节点生成最终回复然后结束。整个结构非常直观。相比于V1 Agent这个图真正把“决策”和“执行”拆开了。agent节点只做决策tools节点只负责调用工具。哪个环节出问题看对应节点的日志就行。2.3 条件路由是控制Agent的关键add_conditional_edges是LangGraph最有价值的地方。它允许你写一个函数根据当前状态动态决定下一个节点。def should_continue(state: AgentState): if state.get(retry_count, 0) 3: return end if state.get(tool_calls): return continue return end条件路由让Agent有了真正意义上的控制流重试、终止、走分支都变成了可读的代码而不是藏在prompt里的隐式指令。实际项目中除了常见的路由判断还要特别关注循环检测。Agent最危险的场景不是“不工作”而是“无限循环”。LangGraph有默认的递归限制但生产环境不能只靠框架默认值。建议在状态里维护一个计数器当工具调用次数或节点重入次数超过阈值时强制走结束分支而不是继续烧token。这一章如果只看概念会觉得抽象但到了TextToSQL实战里条件路由的价值会立刻体现出来。3. TextToSQL实战把自然语言变成可信的SQLTextToSQL是企业级Agent最有代表性的场景之一。不是因为技术最高深而是因为它能集中暴露Agent工程化的所有关键问题理解用户意图、生成结构化输出、验证安全性、处理执行错误、把结果回传成自然语言。3.1 为什么TextToSQL最能检验Agent能力一个完整的TextToSQL任务包含多个环节用户说“上个月华东区销售额前三的SKU是哪些”Agent需要先判断这个问题是否涉及数据库再根据表结构生成SQL然后校验SQL是否安全接着执行查询最后把结果组织成用户能看懂的回答。这已经不是“一次LLM调用”能解决的问题。如果你把全部逻辑塞进一个prompt让模型一口气输出SQL、执行、并组织回答等于把流程控制权全部交了出去。SQL错了怎么办执行超时怎么办用户问的问题不在当前表结构范围内怎么办这些边界问题是TextToSQL能落地的前提。而LangGraph正好把每个环节拆成独立节点让问题可以在特定节点内被解决而不是在prompt里靠运气。3.2 工具设计生成、验证、执行三段分离TextToSQL安全设计的核心原则是LLM只负责生成SQL文本不能直接触碰数据库执行按钮。执行必须经过独立的校验节点。拆成三个节点生成SQL节点接收用户意图和必要的表结构信息返回候选SQL。验证SQL节点用规则和工具检查SQL是否合法、是否只读、是否在允许的查询范围内。执行SQL节点使用独立的数据库连接执行已验证的SQL并加上超时和行数限制。这种设计的最大好处是职责单一。生成节点可以自由发挥验证节点做硬性拦截执行节点兜底保护。任何问题出现时都能立刻定位到具体环节。3.3 用LangGraph把三段流程固化成图TextToSQL的状态至少应该包含以下字段class TextToSQLState(TypedDict): user_question: str schema_info: str sql_candidates: list current_sql: str sql_valid: bool retry_count: int query_result: list final_answer: str trace_id: str图中的节点和边可以这样组织user_question - generate_sql - validate_sql | (valid? yes/no) / \ execute_sql retry/correct | | generate_answer (回 generate_sqlretry_count 1) | END关键的条件路由有两处一处是SQL验证失败后是否重试。如果retry_count 3带着校验错误信息回到生成节点让LLM知道哪里不对如果重试次数达到上限直接返回错误终止流程。这个判断放在validate_sql之后由代码决定而不是让模型自己决定“我还行不行”。另一处是SQL执行失败后的处理。执行返回的错误需要作为反馈传回生成节点让LLM修正。但同样需要限制次数防止死循环。这种流程图一铺开你会发现整个Agent的行为非常透明。每一步都有依据每一步都可追溯。3.4 实战中必须控制的几个风险点TextToSQL最容易被低估的是风险控制。建议至少关注这几个点只读校验验证节点必须确认SQL是SELECT语句禁止INSERT、UPDATE、DELETE、DDL。正则只是第一层最好再结合SQL解析器做语法级校验。权限隔离执行SQL的数据库账号应该是只读账号连接参数也要和业务写库严格分离。资源保护查询必须加LIMIT连接必须设置超时避免一条大查询拖垮数据库。Schema裁剪不要把整个数据库的完整DDL都塞给LLM。只把相关表的表名、字段名、字段类型、注释和示例值传过去既能省token又能降低干扰。方言匹配不同数据库的SQL方言差别很大。生成SQL时要在prompt中明确指定方言例如MySQL、PostgreSQL、SQLite避免模型输出通用SQL导致执行报错。可以加一个引用块提醒注意TextToSQL落地时宁可先拒绝问题也不要放行一条不确定的SQL。规则的严格程度应该大于生成的灵活程度。4. 可观测部署Agent上生产前最容易欠的账很多Agent项目停在Demo阶段根本原因不是做不出来而是上线之后出了问题不知道怎么查。Agent的可观测性直接决定了它能不能从玩具变成生产系统。4.1 为什么Agent调试比普通API难得多普通API接口是请求 - 响应一次调用日志里记录入参和出参就够了。Agent不同一次用户请求可能触发多次LLM调用、多次工具调用、多条分支路径。最终结果是整条链路共同作用的结果哪个节点出错都可能导致最终输出异常。更麻烦的是Agent的错误往往是“软错误”不报错但结果不对。LLM可能选错了工具可能生成了一条不合理的SQL可能在某个分支里把中间结果填错了状态字段。如果没有完整的运行轨迹你只能对着最终结果猜原因。4.2 最小可观测方案日志、追踪、指标在不引入复杂平台的情况下可以先搭一套最小可观测方案包含三个部分追踪Trace为每次用户请求生成一个trace_id贯穿所有节点。每个节点的进入、退出、报错都记录这个trace_id这样可以把一次Agent执行的所有事件串起来。日志Log在每个节点函数外层加日志装饰器输出节点名、输入状态的关键字段、输出状态的关键字段、运行时长、token消耗。日志建议使用JSON格式方便后续检索和分析。import json import logging import time import uuid logger logging.getLogger(agent_trace) def trace_node(name): def decorator(func): def wrapper(state): trace_id state.get(trace_id) or str(uuid.uuid4()) start time.time() logger.info(json.dumps({ trace_id: trace_id, node: name, event: enter, state_keys: list(state.keys()) }, ensure_asciiFalse)) try: result func(state) except Exception as e: logger.error(json.dumps({ trace_id: trace_id, node: name, event: error, error: str(e) }, ensure_asciiFalse)) raise elapsed time.time() - start logger.info(json.dumps({ trace_id: trace_id, node: name, event: exit, elapsed: round(elapsed, 3) }, ensure_asciiFalse)) return result return wrapper return decorator指标Metrics记录每次Agent运行的总耗时、总token消耗、LLM调用次数、工具调用次数、重试次数。这些数据可以用于成本控制和性能优化。这里有个容易被忽略的点不要把完整prompt和工具入参原样记录到日志。生产环境中的日志可能包含用户隐私或业务敏感数据先把关键字段脱敏再落盘。4.3 从本地开发到生产服务的部署路径开发阶段使用uv run langgraph dev这类开发模式很方便自带热更新和调试面板适合本地迭代。生产部署时更常见的做法是直接使用标准的ASGI服务框架把编译好的图封装成HTTP接口。原因在于开发模式带有额外的辅助行为虽然方便但不一定适合生产环境的运维规范。生产环境需要的是标准的接口管理、鉴权、限流、健康检查、日志采集和进程管理直接用ASGI服务把这些能力接入现有体系比依赖开发服务器再套一层壳更稳妥。部署时需要额外考虑并发隔离每个请求要使用独立的AgentState不能让多个用户请求共享同一个状态对象。超时控制Agent整体可能运行较长时间需要设计合适的超时策略避免请求悬挂。资源保护模型API的rate limit、数据库连接池、向量库连接等都需要在服务层做限流和降级。审计Agent调用过的工具、执行过的SQL、访问过的数据建议记录审计日志满足安全和合规要求。4.4 Agent问题排查链路实际排查Agent问题时按这个顺序走效率最高先看现象没返回、报错、返回错误内容、死循环、还是速度异常。拉通trace用trace_id找到整条执行路径确认最后一步停在哪个节点。定位节点是进入generate_sql后就报错还是validate_sql拦截掉了还是execute_sql超时。检查输入进入该节点时状态里的关键字段是否完整schema信息是否传全了用户问题是否被截断。检查状态流转上一个节点返回的状态更新是否符合预期有没有字段被覆盖、丢失或误写。检查环境和参数模型API是否正常、依赖版本是否匹配、超时设置是否合理、重试次数是否耗尽。判断工具边界工具本身是否有问题比如数据库返回格式异常、Schema信息过时、工具返回结果过大超出LLM上下文。这条链路的核心思路是先定位节点再检查该节点的输入和输出最后再考虑环境和参数。不要一上来就调prompt。很多Agent问题根本不是prompt不行而是状态传递错了。5. 从一个Demo到一组工程约束写Agent不难难的是让Agent在明确边界内可靠工作。最后这部分聊一下落地时的适用边界和推进思路。5.1 适合Agent的场景与不适合Agent的场景适合用Agent的场景有一些共同特征流程边界清晰、工具数量可控、需要组合多个能力、结果可以验证、失败有明确回退路径。比如TextToSQL、客服工单分类加自动回复、测试报告生成、数据报表问答这些都是典型的窄领域Agent。不适合用Agent的场景也要心里有数规则完全固定、不涉及动态决策的流程直接写代码或SQL效率更高输出质量要求极高、不允许随机波动的场景Agent需要额外的验证器和人工审核才能撑住算力和成本受限的场景多轮LLM调用会放大消耗没有日志和追责能力的团队先不要急着把Agent推上线。关键判断标准是如果这个问题用传统代码能解决就用传统代码。Agent应该用来解决“传统代码写不好、纯LLM又管不住”的中间地带问题。5.2 给刚接触LangGraph的人几点建议不要试图一上来掌握所有概念。先跑通一个只有一个工具调用的图把状态、节点、边这三个基础概念吃透然后增加条件路由让Agent在特定条件下不再调用工具再逐步引入子图、并行分支、人工确认等高级能力。学习路径可以这样拆先写一个不调用工具的Agent输入问题LLM直接回答走固定边。增加一个工具让Agent根据问题决定是否调用工具。增加条件路由当工具调用失败时重试超过次数终止。增加子图把“工具调用结果校验”封装成子图在主图中复用。增加可观测用装饰器记录每个节点的运行轨迹。最后再考虑部署和并发。每一步都跑通再进入下一步。流程越简单出问题时越容易定位。5.3 五步落地框架把Agent做成可复盘、可迭代的产品把一次性的Demo变成可以长期迭代的产品建议按这五步走划定窄场景不要一开始做“全能助手”先圈定一个边界清晰的场景比如“只支持查询10张销售相关的表”。跑通闭环用最小流程打通“需求 - 生成 - 验证 - 执行 - 回答”的完整路径。固化边界把工具白名单、终止条件、验证规则、重试上限写进代码而不是留在prompt里。接入可观测从第一版开始就记录trace、日志、token消耗和耗时越早接越容易排查。小流量上线并建立回退机制先让少量用户试用同一场景保留传统流程作为备份Agent异常时能快速切换。这个框架看起来不惊艳但很实用。它解决的核心问题是Agent项目从“能跑”到“能长期跑”之间需要补充的工程化能力。回到最开始的那个判断LangGraph确实让Agent开发变得更可控但真正决定一个Agent能否在企业环境里存活下来的从来不是框架本身而是你对流程边界、状态设计、安全约束和可观测性的掌控程度。框架只是把这些问题摆到了台面上解决它们仍然要靠工程经验和持续迭代。

LangGraph实战：从LangChain迁移到状态图Agent的完整指南

相关推荐

API版本升级实战：统一接入层从V1到V2的稳健迁移指南

用双色球历史数据练手：Excel与MySQL数据处理全流程实战

原创职业与摸金循环：RPG服务器如何从“欢迎你”做到“留得住”

更多资讯

常用虚机模式

如何快速搞定DS4Windows：轮询率、HIDHide隐藏手柄与多控制器输出槽完整指南

CC Switch v4.0.19 升级指南：第 12 个应用 Kimi Code 接入与用量页重排的完整说明

如何正确评测ternlight的性能：冷启动、热延迟与吞吐量测试完整教程

《Codex CLI 在 Windows 上如何安装？从环境配置、登录到首次运行的完整实测》

【Agent-01】理解 Agent：目标、执行与证据

今日更新

淘宝商品详情API开发实战与性能优化指南

Unity Package Manager刷新错误排查与解决方案

Java record 规范构造器能否被反序列化或反射绕过

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？