LangGraph多智能体工作流实战：从零构建图编排系统

最近折腾LangGraph的时候，我一直在想一个问题：为什么大家都开始用“图”来编排多智能体工作流。以前我们写Agent，无非是在一个while循环里反复调模型、调工具，最多再加一个记忆列表。一旦需要两个Agent协作，或者一个Agent的工作结果要分发给另外一个人处理，代码立刻变得拧巴。循环里套循环，状态散落在一堆临时变量里，程序跑着跑着你自己都不知道当前是哪个智能体在说话。

LangGraph这套东西解决的就是这个尴尬。它把整个多智能体协作流程重新定义成一张有向图：每个智能体是一个节点，节点之间用边连接，边上可以挂条件，条件满足就往下走，不满足就回退重跑。这种建模方式让我第一次觉得“多智能体编排”不再是个玄学概念，而是能真正落到代码上的工程实践。这篇文章就围绕我最近做的那个模拟项目X，完整拆解一下从零构建一个LangGraph多智能体工作流的全过程，包括设计思路、核心概念、代码实现、踩过的坑，以及一些只有实操才能发现的细节。

1. 为什么放弃传统Agent循环，改作图结构编排

1.1 传统多Agent脚本的问题出在哪

先复盘一下老做法。假设你要做一个“内容创作团队”：一个Agent负责想选题，一个Agent负责写初稿，一个Agent负责校对润色。最自然的实现方式是什么？先把Agent1的结果塞进变量result1，再把result1拼进Agent2的提示词，拿到result2，再传给Agent3。看起来没什么问题，但你会发现这套模式根本撑不过三种情况。

第一种情况，Agent2觉得初稿方向不对，需要回退到Agent1重新起草。这时候循环嵌套就得自己画流程图，然后手动管理返回路径，代码里的flag变量会越来越多。第二种情况，Agent1和Agent2其实可以并行跑，但脚本结构默认串行，想并行就得改写调度逻辑。第三种情况，三个Agent中间态太多了，你在调试时想看某一步的输出，只能打日志翻半天。更麻烦的是，一旦任务变成“不确定多少个Agent参与、不确定谁先谁后”的动态流程，线性脚本直接崩盘。LangGraph把“流程”剥离成显式的图结构，这些问题在建模层面就被解决了。

1.2 图结构从根上改变了什么

用图来编排多智能体，带来的第一个改变是“流程可见”。StateGraph的每一步都在一张明确定义的状态图上走，你可以一次性看到从哪里出发、经过哪些节点、有哪些分支、在哪里汇聚。第二个改变是“节点复用”。同一个节点可以在多条路径中被复用，比如“检查内容质量”这个节点，既可以出现在初稿阶段，也可以出现在终审阶段，不需要复制粘贴函数。第三个改变是“循环可控”。图里允许有环，但这个环不是隐式的while循环，而是有名字、有入口、有出口的显式边。退出循环的条件写在哪一目了然。

我在做模拟项目X的时候最深的一个体会是：多智能体工作流的核心难题不是“让Agent干活”，而是“让Agent之间不吵架”。图结构本身就是一套沟通协议，每个节点只关心自己的输入输出，状态由全局State统一管理，谁也不会偷偷改别人的局部变量。这种有序性是普通代码流程很难提供的。

2. 动手前必须吃透的核心概念：State、Node、Edge

2.1 State是智能体之间唯一的“黑板”

LangGraph里有一个核心概念叫State，它是整张图运行时的全局状态。你可以把它理解为所有智能体共同使用的一块黑板：一个Agent在黑板上写上自己的输出，另一个Agent读取黑板上的内容继续处理。这个State通常用Pydantic的BaseModel来定义，也可以直接用一个TypedDict。

为什么强调类型定义？因为多智能体协作最常见的bug就是状态字段被覆盖。比如Agent1写入了final_answer，Agent2想更新这个字段但忘了合并，结果把Agent1的结果冲掉了。Pydantic的模型约束能在编译阶段就帮你抓住这类问题。我的建议是把State定义成“只追加、少覆盖”的结构：需要更新的字段用列表持续追加，而不是反复赋新值。这样每一步的中间产物都在，后续排查时才知道哪个Agent在哪个阶段说了什么。

2.2 Node就是图上的一次计算

Node是图中真正的执行单元。它可以是调用大模型API的函数，也可以是本地计算函数，甚至是一个异步任务。LangGraph对Node的要求非常少：只要它接收一个State参数，然后返回一个字典，字典里的键会被写入新的State，就足够了。这个接口统一了所有节点的输入输出，对工程化非常友好。

写Node时有几个容易忽略的点：Node函数返回的字典是“增量更新”而非“全量替换”。如果某个节点想删掉State里的某个字段，单独返回空值是不行的，得用专门的删除标记。当时我的同事在模拟项目X里就卡在这个细节上：一个Agent需要“清空草稿”字段，结果返回了一个空字符串，发现下游状态里这个键确实变成空串了，但历史记录里仍然残留着旧值，导致调试时产生了“上下文混乱”的错觉。

2.3 Edge和Conditional Edge决定了路线怎么走

普通Edge就是一条有向边，表示执行完节点A后固定执行节点B。Conditional Edge则是条件边，LangGraph会传入当前State，我写一个路由函数，根据State里的字段内容返回下一个节点的名字。这个机制是图编排的灵魂，所有“如果……就……否则……”的逻辑都要在这里实现。

条件边最常见的应用场景是“质量检查不通过就打回重写”。比如我在模拟项目X里让“校对Agent”返回一个is_ready布尔字段，路由函数检查这个字段：如果是True就去“终审节点”，否则回到“写稿节点”。注意，条件路由返回的必须是节点名构成的路径列表，不是字符串就完事。如果路由返回的节点名不存在，编译报错还算好的，运行时直接抛出异常才是真坑。

3. 实战拆解：三智能体创作工作流的设计过程

3.1 需求建模：先把业务翻译成图

我在模拟项目X里要处理的任务是“写一篇带有明确观点和风格要求的文章”，流程是：策划方向 → 生成初稿 → 专业校对。如果严格按顺序跑当然可以，但我想让整个过程更接近真实团队协作：策划Agent输出“选题大纲”后，写稿Agent觉得内容太浅，可以直接退回给策划Agent补素材；校对Agent发现错别字或逻辑漏洞，不只要改正，还要把问题原因回传给写稿Agent，由它重新修订。

这种非线性的协作需求如果拍成代码，就是一张包含环路的图。我花了半天时间在白板上画节点和边：三个核心节点分别是策划Agent、写稿Agent、校对Agent，外加一个入口节点和一个终点节点。入口节点负责初始化State，终点节点负责汇总最终结果。图里有两条环路：一条是“写稿 → 校对 → 写稿”，另一条是“策划 → 写稿 → 策划”。当时我还担心环路太多会不会乱，实际操作下来，每条路都有明确的条件边，反而比平铺直叙的代码好追踪得多。

3.2 每个节点内部做什么

策划Agent接收需求描述，输出选题名、文章大纲和核心观点列表；写稿Agent读取大纲，结合一个可选风格参数，生成完整初稿；校对Agent读取初稿，输出修订版文本、问题清单和is_ready标记。每个Agent其实就是一个大模型调用函数，我统一封装了一个call_llm函数，传入系统提示词和用户内容，返回解析后的结构化结果。

这里要提一个容易踩的细节：不要在每个Node里重复“搭建提示词”的逻辑。我在模拟项目X里把提示词模板单独抽了一个文件，每个Node通过节点名称从配置里加载对应模板。这样改提示词不用动代码结构，对后续迭代非常有帮助。另一个细节是：Node里的LLM调用一定要做异常捕获。网络波动、超时、JSON解析失败，这些在本地测试时不太会触发，一旦跑真实服务就会频繁冒出来。我当时的做法是统一捕获后返回一个约定好的错误状态字段，由路由函数判断是重试还是终结。

3.3 给“多个智能体”加上可监督的循环边界

有循环就一定要有终止条件，否则图就是在玩火。我设置的终止条件分两层：第一层是迭代次数硬限制，比如写稿、校对循环最多3轮，策划回退最多2轮；第二层是质量判断，校对Agent返回的is_ready为True就离开环路。为方便定位问题，我还给State加了一个round_count字段，每次进入环路节点前自动加一。

把两个条件叠加起来，路由函数的逻辑很清晰：如果round_count达到上限，强制走终结点；否则根据is_ready判断是否继续回退。这里我强烈建议在State里加一个debug_log列表字段，每次路由函数做选择时，都往里面append一条记录，比如“round=2,is_ready=False,go_to=writer”。表面上看只是多了一个字段，实际上排查环路行为时它就是活动的“黑匣子”，比事后看日志高效太多了。

4. 完整代码实现：把设计图落成可运行的程序

4.1 定义State Schema和节点函数

我用Pydantic来定义State，核心字段包括：topic、outline、draft、revised_draft、issue_list、is_ready、round_count和debug_log。一个关键设计是draft字段在回退时会追加到draft_history列表中，这样既保留每一步历史，又不会覆盖上一次的初稿。

python复制from typing import List, Optional
from pydantic import BaseModel, Field

class WritingState(BaseModel):
    topic: str = ""
    outline: str = ""
    draft: str = ""
    draft_history: List[str] = Field(default_factory=list)
    revised_draft: str = ""
    issue_list: List[str] = Field(default_factory=list)
    is_ready: bool = False
    round_count: int = 0
    debug_log: List[str] = Field(default_factory=list)

节点函数的写法要注意：入参是整个状态对象，返回值是要更新的字段字典。我的策划节点会返回outline和debug_log，写稿节点返回draft、draft_history和debug_log，校对节点返回revised_draft、issue_list、is_ready和debug_log。这里所有更新都是追加式，没有直接覆盖旧值的地方，最大程度减少了状态丢失问题。

4.2 实现路由函数与图结构

路由函数是条件边的核心，我给它取名decide_next_step。它的逻辑是读取出当前State中的is_ready和round_count，然后决定去向。

python复制def decide_next_step(state: WritingState):
    state.round_count += 1
    state.debug_log.append(f"round={state.round_count}, is_ready={state.is_ready}")

    if not state.is_ready and state.round_count < 3:
        return ["writer"]
    if state.outline == "" or state.draft == "":
        return ["planner"]
    return ["end"]

然后定义节点实例并用StateGraph把这些点串起来。先为每个Agent创建对应的节点对象，再把入口节点、Agent节点和终结点都注册进去。

python复制from langgraph.graph import StateGraph, START, END

def entry_node(state: WritingState):
    return {"round_count": 0, "debug_log": ["entry:start"]}

def planner_node(state: WritingState):
    # 大模型调用后生成outline
    return {"outline": "...", "debug_log": ["planner:done"]}

def writer_node(state: WritingState):
    # 大模型调用后生成draft
    return {"draft": "...", "draft_history": [state.draft], "debug_log": ["writer:done"]}

def reviewer_node(state: WritingState):
    # 大模型调用后生成is_ready
    return {"revised_draft": "...", "issue_list": [...], "is_ready": True}

graph = StateGraph(WritingState)
graph.add_node("entry", entry_node)
graph.add_node("planner", planner_node)
graph.add_node("writer", writer_node)
graph.add_node("reviewer", reviewer_node)

graph.add_edge(START, "entry")
graph.add_edge("entry", "planner")
graph.add_edge("planner", "writer")
graph.add_edge("writer", "reviewer")
graph.add_conditional_edges("reviewer", decide_next_step, {
    "writer": "writer",
    "planner": "planner",
    "end": "end",
})
graph.add_edge("end", END)

app = graph.compile()

这里有一点需要解释：add_conditional_edges的第三个参数是把路由函数返回值映射到节点名的字典。如果decide_next_step返回的是“writer”，那就走writer节点；返回“end”就走终结点。需要注意的是，映射表里的值必须在图中已经注册过，不然运行时找不到目标节点。

4.3 编译与运行：观察中间状态

编译之后，执行入口非常简单。我给输入topic传了一个测试标题，然后调用invoke方法。LangGraph会返回最终的State快照，里面包含所有中间字段。

python复制initial_state = WritingState(topic="用LangGraph构建多智能体工作流")
result = app.invoke(initial_state)
print(result["revised_draft"])
print(result["debug_log"])

第一次跑的时候，我发现一个很有趣的现象：由于我一直用追加式更新debug_log，整个流程的所有路由决策都在里面，打印出来就是一条完整的时间线。这比任何日志方案都直观。如果你需要更细的看每一步发生了什么，LangGraph还支持传入config参数，设置checkpointer之后，可以像回放录像一样逐步查看每个节点的输入输出。我在模拟项目X里没有用复杂持久化，只用了一个内存态的checkpointer，在调试阶段效果就非常好。

5. 真实运行中的常见问题与排查实录

5.1 状态字段被静默覆盖

这是我在整个项目中最常遇到的问题。最开始我把draft字段设计成单一字符串，校对Agent回退给写稿Agent后，旧草稿直接被新草稿覆盖，问题来了：校对Agent看到的新草稿只有“上一轮修改后的版本”，完全没有“上一版”信息，它提的问题自然就变得上下文不连贯。后来我改成draft_history列表，每次新草稿生成前先把旧草稿追加到历史里，才彻底解决。如果你发现Agent行为“失忆”，大概率是状态字段被覆盖了，建议优先检查有没有用列表保存历史。

5.2 条件路由返回路径列表，不是字符串

这里值得单独说。LangGraph的conditional_edges路由函数要求返回一个列表，或者一个可以被映射的单个字符串。我一开始返回了字符串"writer"，运行时没问题；后来改成同时支持多条路径时返回["writer", "planner"]，才发现这个接口本身是按“下一步可以走哪几条路”设计的。这带来一个很有用的能力：你可以在一次条件判断里同时触发多个下游节点，实现扇出。比如校对不通过时，既可以回到写稿，也可以同时通知策划补充资料。初学者容易把这个接口当成“指定一个节点”来用，其实它更适合表达“本次决策允许进入的节点集合”。

5.3 环路跑飞，没有任何输出

有两天版本里，我的图跑起来就像死循环，终端卡了很久才返回结果。查下来发现是路由条件写反了：is_ready=True时本应走向终点，我却写成了继续回退。当时debug_log字段救了大命，每条记录里都能看到round_count一直往上飙到几十。后来我在路由函数开头就做了硬性校验，如果round_count超过设定的上限，强制返回终结点路径。这样即使业务逻辑判断有bug，图也不会无限跑下去。墙上的白板提醒我：多智能体工作流在运行时是不可预测的，但图的结构可以提前设好安全阀。

5.4 异步节点混用时状态丢失

我第二次重构时把写稿Agent改成了异步调用，想让它在等待大模型响应时并行执行其他节点。结果发现State的更新不是线程安全的，两个节点同时往debug_log里追加内容，偶发出现丢记录。LangGraph官方其实支持async节点和异步invoke，但我当时没注意要全程使用await调用链，混合了同步和异步节点，状态更新就出现了竞态。解决办法也很简单：要么全图统一异步，要么彻底保持同步。项目周期紧的话我建议先同步跑通全流程，再按性能瓶颈去改异步。异构并发看起来简单，实际调试成本不低。

5.5 常见问题速查表

6. 项目落地的几个进阶经验

6.1 用廉价大模型代理跑通整条图

真实项目里，大模型API的费用是个不能回避的问题。我在模拟项目X里反复调试图结构时，如果每次跑全流程都调真实大模型，预算撑不住。后来我加了一个环境变量开关，把节点里的LLM调用替换成一个预设模板的假函数：输入什么关键词，就返回写死的看似合理的文本。这样整张图的“路由形状”可以先跑通，我只需要验证图的结构、状态传递和环路逻辑，等到所有路径都调试无误后，再去掉开关接入真实模型。这个技巧在开发阶段的性价比极高，强烈建议先模拟再接入。

6.2 把提示词模板从代码里抽出来

第二个经验来自一次血的教训。我把提示词直接写在节点函数里，后来想调整校对Agent的规则，不得不改代码重新部署。更惨的是，三个节点的提示词风格不统一，同一个术语有着不同叫法，Agent之间经常“说不到一块”。我把模板改成外部配置文件后，同一套术语自然统一了，Agent之间的协作也顺畅不少。多智能体工作流里的提示词，某种意义上就是它们之间的“共同语言”，不一致的话图结构再正确也没用。

6.3 给图结构增加可观测性

最后一个经验是关于可观测性的。多智能体工作流和传统线性程序不同，节点之间来回跳转，你对“当前状态”的判断很容易过时。我在State里放了一个全局的trace字段，把每一次节点名称、路由决策、关键输出摘要都塞进去。最终交付的result里，用户只要看trace就能大概知道这篇文章是怎么被一步步写出来的。我还把trace写进了日志文件，排查问题时按trace timeline去定位，效率比扫屏高很多。哪怕是最简单的多智能体项目，也建议把“链条轨迹”作为一等公民记录下来。

如果你也是第一次接触LangGraph，我建议不要一上来就搞十几个Agent的大图。先用一张三个节点的小图，把State的流转、条件边的路由、循环的控制彻底搞明白，再逐步加复杂度。我在跑模拟项目X的初期，最大的收获是理解了“图结构”并不是为了炫技，它真的是让多智能体协作从不可控走向可控的关键抽象。当你看着一张自己画的图在程序里变成一条条清晰可见的执行路径时，那种感觉和之前写简单循环相比，完全不是一回事。