LangGraph实战：从Chain到复杂智能体的工程化落地全指南

做Agent开发这事，很多人一开始觉得难在“模型怎么调”，真上手之后就会发现，难的是“业务逻辑怎么编排”。我前阵子在公司做一个销售场景的智能体，要求Agent能查客户资料、调CRM接口、自动生成跟进摘要、遇到异常订单还要停下来转人工审核。最开始用LangChain的链式调用硬写，改了两版就彻底撑不住了，分支一多，代码变得越来越乱，后来整体切到LangGraph重写核心流程，才把这事理顺。这篇就基于LangGraph，聊聊我开发这类复杂智能体的完整思路、落地步骤，以及过程中踩过的坑。想搭生产级Agent的朋友，这篇应该能帮你少走不少弯路。

1. 为什么我放弃了纯LangChain链式写法

1.1 一个从“能跑”到“难维护”的真实转变

先说说最基础的对比。LangChain早期的核心思路是Chain，也就是把“取变量、调模型、解析结果”串成一条固定链路。比如做RAG问答系统时，RetrievalQA这种链确实好用，代码写起来也短，几步就接完了。但到了复杂智能体阶段，问题就冒出来了：如果是自由对话和工具调用来回切换，你得在链里不断塞callback、塞条件判断、塞循环逻辑，整个执行流是隐式的。我那个销售场景里的Agent，需要根据用户一句话决定调用哪个工具、要不要追加检索、要不要先给客户做标签分类、还是直接拒答并转人工。用Chain硬写出来的代码，每个分支都是一大坨if else，调试一次半小时起步，新增一个工具就要重排整个链结构。

真正让我决定抛弃Chain写法的，是一次线上事故。某天用户问了一句“你们和XX公司的合同进展到哪里了”，模型在工具调用里抽到的参数不太规范，链上某一步没有兜底，整个流程直接throw了一个JSON解析异常，下游所有节点的上下文全丢了。这种问题在固定链路里特别难防，因为链本身不知道什么时候该重试、什么时候该跳过、什么时候该交给其他节点。

1.2 LangGraph核心建模方式：节点、边、状态

LangGraph让我最舒服的一点，是它把Agent的执行流画成了一个有向图。所谓“LangGraph开发复杂智能体”，本质上就是在用图的方式管理复杂业务流。

它只有几个核心概念，但比Chain灵活得多：

• State（状态）：整个图的共享数据层。所有节点都从State里读数据，也可以往State里写数据，相当于一个全局记忆黑板。
• Node（节点）：每个节点做一件事。可以是一个函数，负责检索、调用工具、让模型推理，或者触发某种外部动作。
• Edge（边）：定义节点之间的执行顺序，A跑完走B。
• Conditional Edge（条件边）：不固定下一步，而是根据某个判定函数的返回结果，动态选择下一个节点。

这种建模方式最大的好处是“流程可见、分支可控”。复杂智能体的本质无非是“在什么条件下做什么事”，用图来建模，你不需要把所有逻辑都压在代码里硬编码，只需要把节点定义好，把路由规则写清楚，剩下的执行交给LangGraph引擎去跑。我从LangChain迁移过去之后，销售Agent里那些乱七八糟的分支逻辑，全部变成了图上一条条边，出了问题看状态流转记录，一眼就能定位在哪个节点挂了。

1.3 和Dify这类平台工具的本质区别

之前也有朋友问，既然有Dify智能体平台、Coze这类的可视化平台，搭一个Agent拖拖拽拽就出来了，为什么还要用LangGraph写代码？

我的回答是：看你的项目Stage。Dify这类平台，适合原型快速验证、非技术同学做简单工作流、以及不需要深度定制的中小场景。但一旦涉及复杂业务，比如要接自家内部系统、要做细粒度的权限隔离、要人工审核节点和外部流程引擎打通，低代码平台往往会在某个地方卡住。Dify的自定义工具虽然也让写代码，但平台本身的部署、版本控制、代码评审、灰度发布，都不如直接在一个代码仓库里做工程来得顺滑。

LangGraph在我看来是“开发框架”，不是“平台”。它给你的是一个标准的执行引擎和一套清晰的扩展点，真正怎么编排、怎么设计，全在开发者手里。所以做生产级复杂智能体，我现在的习惯是：先用Dify这类平台快速验证业务逻辑，确认需求后，再用LangGraph把它工程化落地。两个不是替代关系，而是不同阶段的选择。

2. 环境准备：LangGraph安装与第一个能跑的图

2.1 安装前的环境选择

LangGraph是Python库，目前官方推荐Python 3.9以上。我自己用的是3.11，实测下来不管是StateGraph标准库还是异步节点，兼容性都挺好。如果项目里已经有大模型封装库，比如LangChain或LangChain Community，建议一起装，因为LangGraph和LangChain的模型API是打通的，不用额外去写一套Prompt调用逻辑。

安装之前强烈建议开虚拟环境。Python项目最忌讳把依赖混在一起装，特别是LangGraph这种迭代快的库，今天装的版本和三个月后的版本API很可能就有差异。我用的是venv：

bash复制python -m venv .venv
source .venv/bin/activate  # Windows用 .venv\Scripts\activate

2.2 安装LangGraph及依赖

核心安装就一条命令：

bash复制pip install -U langgraph langchain-openai

langgraph是主库，langchain-openai是OpenAI风格的模型接入包。如果你用的是国内模型厂家的接口也没关系，它们绝大多数兼容OpenAI SDK格式，直接拿langchain-openai把base_url换成厂家地址就行。我那个销售Agent用的就是这么干的，模型层没有任何额外开发。

装完之后验证一下版本，免得后面踩版本坑：

bash复制python -c "import langgraph; print(langgraph.__version__)"

如果还打算用LangGraph的后台持久化功能，需要额外装一个检查器后端：

bash复制pip install -U langgraph-checkpoint

这个先不用急，后面讲记忆和断点时会说到。

2.3 十分钟写一个最小可运行的Flow

装好环境后，别急着写复杂东西，先跑通一个最小图。我习惯用“搜索问题→判定是否调用工具→生成答案”这个最小流程来做环境验证，代码大概长这样：

python复制from typing import Annotated, TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]
    query: str
    search_result: str

def search_node(state: AgentState):
    # 这里假装调一下搜索接口
    return {"search_result": f"模拟搜索结果: {state['query']}"}

def need_tool(state: AgentState):
    if "时效" in state["query"] or "最新" in state["query"]:
        return "search"
    return "answer"

def answer_node(state: AgentState):
    return {"messages": [{"role": "assistant", "content": f"答案是: {state['search_result']}"}]}

graph = StateGraph(AgentState)
graph.add_node("search", search_node)
graph.add_node("answer", answer_node)
graph.add_edge(START, "search")
graph.add_conditional_edges(
    "search",
    need_tool,
    {"search": "search", "answer": "answer"}
)
graph.add_edge("answer", END)
app = graph.compile()

result = app.invoke({"query": "今天的最新销售数据是多少"})
print(result["messages"][-1]["content"])

跑通这段代码，就意味着你的LangGraph环境完全正常了。后面所有复杂逻辑，都是在这个图上不断加节点、加边而已。很多教程一上来就讲多智能体、讲复杂状态机，反而让新手卡在环境阶段，我这里建议先把这个小图跑通，再慢慢往上叠。

3. 状态设计：给复杂智能体打好“数据地基”

3.1 State是贯穿全程的共享内存

LangGraph里的State不是数据库表，它更像一个”运行时共享内存“。所有节点看图，只能看到State里有的字段，写入时也只能往State里写。这个设计让每个节点天然成为一个”只依赖入参、只产生出参“的函数，调试起来非常容易。

我开发销售Agent时，State字段大概设计成这样子：

python复制class SalesAgentState(TypedDict):
    messages: Annotated[list, add_messages]
    customer_id: str
    customer_info: dict
    crm_data: dict
    intent: str
    draft_reply: str
    needs_human_review: bool
    review_result: dict

每个字段承载一个明确职责：customer_id是用户输入的原始标识；customer_info是检索后的客户画像；crm_data是工具调用结果；intent是意图识别结果；needs_human_review是流转标志位；review_result放人工审核回来后的结论。

做状态设计时，最忌讳的是把临时变量一股脑塞进State。有人图省事，把“这个中间结果只在这个节点用一次”的变量也塞进去，结果State越滚越大，每个节点都在读一堆无关字段，既难调试又容易脏。我的原则是：State里只放“跨越节点边界、确实需要共享”的数据，节点内部计算的临时结果，就放在函数局部变量里。

3.2 Reducer决定了多路写入怎么合并

默认情况下，State里的字段是“覆盖式更新”：后写的节点覆盖先写的。但有些字段不是这个语义，比如对话消息列表，应该是“追加式”的，而不是覆盖式。

LangGraph用Annotated加Reducer的机制来解决这个问题。看前面代码里我写的：

python复制messages: Annotated[list, add_messages]

这里的意思就是：messages这个字段的写入方式，不是覆盖，而是调用add_messages这个Reducer，把新的消息追加到旧列表后面。LangGraph框架内置了add_messages，也可以自己写Reducer函数。比如我想把多个节点的customer_info字段做合并，而不是后者覆盖前者，就写一个自定义Reducer：

python复制def merge_dicts(a: dict, b: dict) -> dict:
    if a is None:
        return b
    if b is None:
        return a
    return {**a, **b}

customer_info: Annotated[dict, merge_dicts]

写Reducer的时候要注意类型一致性。我踩过一次坑：State里写的是list，某个节点返回了None，Reducer拿到None直接崩了。后来所有Reducer函数第一行第一件事就是判空，养成习惯后这种问题就再没出现过。

3.3 状态快照与临时变量该放哪

复杂智能体还有一个隐藏问题：同一个图可能被并发调用，不同会话之间的State不能串。LangGraph通过config里的thread_id来隔离会话，每个thread_id是一条独立的State上下文。

我这里说的”状态快照“，指的不是LangGraph内部的checkpoint机制，而是自己业务上要用到的中间态。比如销售Agent在处理一个客户时，要先拉取客户360视图，再计算推荐策略，最后生成本次沟通摘要。这个过程如果中途断电、超时或出错，整个状态就白费了。所以我在每个关键节点结束后，会把当前State里的关键数据以JSON形式存到Redis里，key就是agent:{thread_id}:snapshot，TTL设成30分钟。这样即使节点崩溃，也能通过一条快照恢复现场，而不是让用户从头再来。

要注意区分快照和Checkpoint。快照是自己业务数据的冗余备份，Checkpoint是LangGraph框架层面的执行状态持久化，后面单独讲。

4. 从线性到条件：让模型自己决定下一步往哪走

4.1 条件边解决分支问题

固定链路只能解决“按顺序执行”的场景，复杂智能体的核心是动态路由。销售Agent里最常见的动态场景是：用户说“帮我查下A客户的合同”，Agent要先判断这是查询意图、修改意图还是新增意图；如果是查询，还要判断是查合同、查订单、还是查回款；不同意图对应完全不同的工具链。这类逻辑如果用Chain硬编码，代码量会爆炸，而且每加一个意图就要改一大段代码。

LangGraph的条件边，直接用函数返回值作为路由信号。前面示例里的need_tool函数，返回字符串，框架根据返回值和路由表决定下一步：

python复制def route_by_intent(state: SalesAgentState):
    intent = state["intent"]
    if intent == "query_contract":
        return "contract_node"
    if intent == "modify_order":
        return "modify_confirm_node"
    return "support_fallback"

graph.add_conditional_edges(
    "intent_node",
    route_by_intent,
    {
        "contract_node": "contract_node",
        "modify_confirm_node": "modify_confirm_node",
        "support_fallback": "support_fallback",
    }
)

这里的路由函数本身可以是规则判断，也可以接模型调用。最灵活的做法是让大模型做意图识别，输出固定枚举值，然后代码根据枚举走条件边。这样既保留了模型的语义理解能力，又把路由的确定性握在自己手里。

4.2 面向“多技能”的工具注册

热点搜索里有一个高频词叫“LangGraph怎么增加skill”。LangGraph官方没有单独的“Skill”概念，但社区里的Skill，本质上就是“一组相关性很强的工具集合，挂载到某个节点上”。

我现在的做法是给每个技能组一个独立的Python模块，模块内定义工具函数，函数上打@tool装饰器。比如销售场景有“客户检索技能”，里面包含三个工具：

python复制from langchain_core.tools import tool

@tool
def get_customer_basic_info(customer_id: str) -> dict:
    """根据客户ID查询客户的基本信息，包括公司名、联系人、行业等。"""
    return crm.query_basic(customer_id)

@tool
def get_customer_recent_orders(customer_id: str, days: int = 30) -> list:
    """查询客户最近N天的订单记录。"""
    return crm.query_orders(customer_id, days)

@tool
def get_customer_contract(customer_id: str) -> list:
    """查询客户当前有效的合同列表。"""
    return crm.query_contracts(customer_id)

然后在节点里，把这一组工具绑定给模型：

python复制from langchain_openai import ChatOpenAI

def customer_info_node(state: SalesAgentState):
    model = ChatOpenAI(model="gpt-5-mini", temperature=0)
    tools = [get_customer_basic_info, get_customer_recent_orders, get_customer_contract]
    model_with_tools = model.bind_tools(tools)
    # 然后把模型对工具的调用结果写回State

这样，你想给Agent增加一个技能，只需要新建一个工具模块，在节点里把工具加进bind_tools列表即可。不要把所有工具全部塞到一个节点里，因为模型的上下文窗口有限，工具太多反而容易导致选择混乱。分组注册按业务域隔离，是维护复杂Agent的关键实践。

4.3 多智能体协同：supervisor与分层规划

再往上走，就到了多智能体。销售Agent不是单打独斗，我把它拆成了三个子Agent：一个专门负责客户洞察分析，一个专门负责话术生成，一个专门负责工单处理和转人工。三个子Agent分别跑在自己的小图上，再由一个supervisor统一调度。

多智能体的本质是“分工+调度”。LangGraph里实现supervisor的方式很简单，supervisor本身也是一个节点，它的任务是根据用户原始输入和各个子Agent的汇报结果，决定下一步让哪个子Agent执行。这个调度动作可以由大模型完成，也可以由规则完成。我现在的做法是：

• 用户输入先到supervisor，supervisor用模型判断意图，选择对应子Agent；
• 子Agent执行完，把结果摘要写回State；
• supervisor看到摘要，再判断是要继续调下一个子Agent，还是产出最终回复。

这个模式比单一大Agent更可控。单一大Agent做复杂业务时，输出质量会随着工具数量和上下文体量下降；拆成多Agent后，每个子Agent的上下文范围更小、职责更专注，整体效果反而更稳。代价是设计成本变高了，所以不要一上来就用多Agent，你先跑通单图，确认需求边界后再拆。

5. 持久化、断点与人工审核

5.1 Checkpointer让Agent拥有记忆

复杂智能体和普通问答接口的一个重要区别是“是否记忆上下文”。没有持久化的Agent，每次调用都是全新的State，用户上一句说什么，这一句根本不知道。解决这个问题，LangGraph提供了Checkpointer机制。

最简单的实现是内存版：

python复制from langgraph.checkpoint.memory import MemorySaver

saver = MemorySaver()
app = graph.compile(checkpointer=saver)

config = {"configurable": {"thread_id": "customer_10001"}}
result = app.invoke({"query": "帮我查下这个客户的合同"}, config)

只要thread_id保持不变，后续的每一次invoke都能读到之前的消息历史和State内容。这里有个容易被忽略的点：thread_id是整个持久化的入口标志。我在项目里就是拿“客户ID”直接当thread_id，这样整个会话期间Agent天然围绕这个客户积累上下文，跨会话也不需要再传一堆历史参数。

内存版只适合开发调试。生产环境多实例部署时，每个实例内存不共享，必须换用Redis或PostgreSQL作为Checkpointer后端：

bash复制pip install langgraph-checkpoint-redis

python复制from langgraph.checkpoint.redis import RedisSaver

redis_saver = RedisSaver.from_conn_string("redis://localhost:6379/0")
app = graph.compile(checkpointer=redis_saver)

5.2 human-in-the-loop：关键节点先停一下

销售场景里有一个硬需求：Agent生成的话术草稿，不能直接发给客户，必须经过销售专员确认才能走。这就是经典的human-in-the-loop模式。LangGraph官方提供interrupt机制，可以让执行流在某个节点暂停，等外部确认后再继续。

实现思路这样：在需要人工审核的节点里，调用interrupt挂起流程，把待审核内容存到State里，图返回给调用方一个当前状态。人工审核完成后，调用方带着审核结果重新resume，流程从断点继续往下走。

python复制from langgraph.types import interrupt, Command

def human_review_node(state: SalesAgentState):
    review_request = {
        "draft_reply": state["draft_reply"],
        "customer_id": state["customer_id"],
    }
    review_result = interrupt(review_request)
    return {"review_result": review_result, "needs_human_review": False}

这个机制对我们做业务落地极其重要。你可以想象一下，如果没有这个能力，Agent自动回消息一旦翻车，客户直接把投诉打到销售主管那里，现场会非常难看。有了人工审核节点，关键动作始终在自己人手里，这既是技术设计，也是风控要求。

5.3 可观测性：别等出事了再翻日志

生产级Agent另一个刚需是可观测性。LangGraph的执行链路和普通API调用不一样，一个request里面可能跑了N个节点、多次模型调用、多次工具调用，出了问题靠print日志完全定位不了。LangGraph官方配套了LangSmith，能把每一步的执行情况、token消耗、延迟都可视化出来。如果不想用外部平台，也可以自己加埋点，在每个节点里打结构化日志：

python复制import logging

logger = logging.getLogger("agent")

def search_node(state: AgentState):
    logger.info({
        "event": "node_start",
        "node": "search_node",
        "thread_id": state.get("thread_id", "unknown"),
        "query": state["query"],
    })
    # 业务逻辑

我的经验是，给每个节点加一个统一的开始/结束日志，内容包含thread_id、节点名、耗时、返回的关键字段摘要，排查问题效率能提升好几倍。不要只在出错时打印，Agent执行正常但结果不对的情况太常见了，有完整的节点级日志才能回溯模型在哪一步跑偏。

6. 部署选型：langgraph dev和uvicorn跑服务怎么选

6.1 本地开发：uv run langgraph dev到底帮你做了什么

热点里有人问deerflow uv run uvicorn app和uv run langgraph dev方式的区别，这里我真的要展开说下。

uv run langgraph dev是LangGraph CLI提供的开发模式。启动命令后，它会读取当前目录下的langgraph.json配置，自动识别图对象，并启动一个带调试面板的开发服务器。这个调试面板非常有用，能看到图的实时执行状态、节点输入输出、甚至可以手动触发某个节点，相当于给Agent开发配了个GUI调试器。

适合在本地写图、验证复杂分支时用。缺点是它是开发服务器，性能和安全性都不适合直接暴露到生产。

uv run uvicorn app:app则是标准的Python服务启动方式。app是你自己写的FastAPI实例，你需要自己把编译好的LangGraph图挂到某个路由上，自己处理请求参数、错误码、鉴权逻辑。看起来多写了几行代码，但这些代码恰恰是生产系统需要的控制能力。像deerflow这类项目用uv run配合uvicorn启动Web应用，就是典型的生产服务化思路。

6.2 生产部署：用uvicorn把图包成API

我的生产习惯是：开发用langgraph dev，部署用uvicorn包一层FastAPI。最小示例：

python复制from fastapi import FastAPI
from langgraph.checkpoint.redis import RedisSaver
from src.graph import build_sales_agent

app = FastAPI(title="Sales Agent Service")

redis_saver = RedisSaver.from_conn_string("redis://localhost:6379/0")
graph = build_sales_agent().compile(checkpointer=redis_saver)

@app.post("/agent/run")
async def run_agent(payload: dict):
    thread_id = payload.get("thread_id")
    query = payload.get("query")
    config = {"configurable": {"thread_id": thread_id}}
    result = await graph.ainvoke({"query": query}, config)
    return {"success": True, "data": result}

@app.post("/agent/resume")
async def resume_agent(payload: dict):
    thread_id = payload.get("thread_id")
    review_result = payload.get("review_result")
    config = {"configurable": {"thread_id": thread_id}}
    result = await graph.ainvoke(
        Command(resume=review_result),
        config
    )
    return {"success": True, "data": result}

然后启动：

bash复制uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4

注意这里用ainvoke异步执行，避免FastAPI的worker被阻塞在模型调用上。模型推理一般要2到10秒，同步执行的话并发一高，worker很快就会被打满。用异步就能在等待模型返回期间同时处理其他请求，吞吐量完全不一样。

如果想做流式输出，FastAPI返回StreamingResponse，LangGraph也有.astream_events()方法，可以做逐字输出。我这里没有展开，但生产场景里用户体验要求高时，流式是必选项。

6.3 Java等非Python项目怎么接

有不少团队核心后端是Java，偶尔会想怎么把LangGraph的能力接进来。首先要明确：LangGraph是Python生态的框架，Java项目没法直接调库，最常见的方案是把它做成一个独立的Agent服务，Java通过HTTP远程调用。

我在一个项目里就是让Java端发起一个Agent请求，传thread_id和query两个字段，Agent服务处理完返回结构化的JSON。Java后端拿到结果后，自己负责写业务表、推企业微信、触发工单系统。好处是Agent服务可以独立扩缩容，Java端的同事完全不需要关心LangGraph内部怎么跑，两边只通过接口契约对话。

至于用Java去操作LangGraph的图、修改Python侧的State，我不建议，架构上会很别扭。保持服务边界清晰，比强行统一技术栈重要得多。

7. 我踩过的坑和排查清单

7.1 高频报错与排查速查

这里整理一个我实际开发LangGraph复杂智能体时反复遇到的问题表，基本覆盖了90%的新手场景。

7.2 几个会后悔的实践与回避方案

第一个大坑：把节点设计得太大。我之前为了省事，把一个“客户意向判断”节点写得又长又杂，里面既有规则判断又调模型又查数据库，结果这个节点一出问题，整个图就卡死，调试时根本分不清是模型问题还是数据问题。后来把这个节点拆成intent_rule_node、intent_model_node、enrich_info_node三个独立节点，职责单一，出问题时定位速度和修复速度都大幅提升。节点尽量保持小而专，是LangGraph开发的黄金法则。

第二个大坑：过度依赖模型做路由。模型虽然聪明，但它有随机性，同一个输入可能今天走A分支，明天走B分支。关键业务路由，比如是否转人工、是否发送给客户，我坚持用规则或人工审核兜底，模型只做意图候选排序，不做最终裁决。顺序是：先规则强制兜底，再模型推荐，最后人工确认，这样系统的稳定性才有保障。

第三个大坑：忽略线程安全。开发调试时用内存版Checkpointer没问题，但生产环境多worker部署后，如果还是内存版，不同worker之间完全看不到对方的State。换句话说，用户第一次请求打到worker1，第二次请求打到worker2，worker2就以为这是新会话了。这个问题非常隐蔽，线上要用了才发现。解决办法就是尽早切到Redis或PostgreSQL这类共享后端。

第四个经验，关于模型工具参数容错：模型调用工具时，参数的格式不一定规范，比如日期传成了今天、数字传成了"10"这种字符串、缺字段等等。解决方案是给工具函数加一层参数清洗逻辑，把所有String参数先过一遍类型转换和兜底默认值，再进业务逻辑。肉眼看起来好像多此一举，但线上这样处理过之后，工具调用成功率从80%提到了95%以上，值得做。

我的最终体会

真要在生产里做复杂智能体，技术选型只是第一步，后面大量的工作是状态设计、流程编排、容错兜底和人工审核机制。LangGraph优秀的地方在于它把这些能力都做成了框架级的基础设施，你不用自己造一个流程图引擎，也不用自己设计状态管理，专注把业务节点写好、把图结构想清楚就行。

我个人最大的体会是：不要一上来就追求多智能体、超级复杂的状态机。先把一个最小闭环跑通，让它在真实数据里稳定跑一星期，再逐步增加节点和边。每次只增加一个维度，出问题就知道是新增部分的锅。这才是最稳妥的Agent落地路线。希望这篇把LangGraph做复杂智能体的完整路径和经验写清楚，对正在走这条路的朋友有帮助。