用LangGraph搭的多Agent协作，任务一多就互相死等，怎么排查？

我之前用LangGraph也踩过类似的坑，后来发现多半不是循环依赖的问题，而是子Agent的state里某个字段没显式传下去，导致上游觉得完成了、下游却一直等那个key。建议你先给每个节点加个超时或者重试机制，再在graph里把每个节点的输入输出都打出来，看看是不是某个中间状态被覆盖成None了。另外你试试把主管的决策逻辑简化成显式的路由条件，别让它自己判断，有时候它卡住其实是在等一个永远不会来的tool result。

遇到过类似的，当时是子Agent共享的state里有个字段被多个节点同时读写，LangGraph的supervisor调度又没做超时控制，就卡在条件边判断那了。建议你先给每个节点加个进入和完成的日志时间戳，再在关键边上用asyncio.wait_for包一层超时，能快速区分是节点没被调度还是卡在内部IO。另外检查下是不是用了递归的图结构，LangGraph对循环依赖的默认递归深度限制有时候会静默挂起，可以在编译时把recursion_limit调大试试。

说实话我第一反应就是你这图的循环依赖设计有问题，LangGraph本身对有限次数的循环是支持的，但要是子Agent之间互相等确认，本质上就是逻辑上绕了个死圈。我上次也踩过类似的坑，后来发现是因为我把状态更新放在了节点外面，导致A节点以为B已经跑完了，实际上B还在等A的共享状态刷新，这种状态一致性问题是print根本看不出来的。

建议你先在图的全局状态里加一个显式的step计数或者时间戳，每次节点执行前打出来，看看到底是哪个节点在重复进入还是压根没触发。如果发现某个节点一直在等，但上游确实已经返回了，那大概率是状态里的某个字段没被正确写入，导致条件边一直评估成false，这种情况LangGraph不会报错，就是默默卡住。

另外你排查的时候别只看单个流程，真实数据下并发或者上下文长度变了，很容易触发某些边界条件。我之前用过一个土办法，就是给每个子Agent的返回结果都套一层包含“完成标志”的包装，主图里强制检查这个标志再放行，虽然丑但能快速定位是调度问题还是状态问题。要是你还想省事，直接看LangGraph的debug模式或者把图导出成JSON可视化，比print强多了。

我之前用LangGraph也踩过类似的坑，最后发现多半不是框架不支持循环依赖，而是你图里隐含的边把调度顺序锁死了。像你说A等B、B等A这种，如果两边都有条件边且条件判断依赖对方的状态字段，那状态更新时机稍微错位就会变成永久等待。我现在的排查习惯是先给每个节点加一个超时熔断，比如十秒没触发就强制返回一个哨兵值，这样至少能看出卡在哪个节点上，而不是靠print堆日志。另一个经验是把共享状态里所有字段都列出来，检查每个写操作是在节点开头还是结尾执行的，LangGraph的reducer如果没配好，很容易出现一个节点读到的还是旧值。至于定位状态管理还是节点调度的问题，我一般会在图外面包一层hook，记录每次状态变更前后的hash，如果某个节点执行完状态没变，那大概率是调度逻辑没触发下一步。说实话如果你用的是异步模式，还要考虑事件循环里有没有被阻塞的协程，我之前就是有个子Agent里不小心用了同步requests，直接把整个loop卡住了，表现上跟死等一模一样。你可以试试把agent数量减少到两个最小复现，然后逐步加回来，这比看完整日志快得多。

碰到过类似情况，最后发现多半不是LangGraph的锅，是图里循环边没配好终止条件，或者共享state里某个key被多个节点同时读写导致阻塞。建议先给每个子Agent加超时和状态检查点，跑的时候把每个节点的输入输出hash打出来，能快速定位是卡在状态更新还是节点调度上。另外检查下是不是有隐性的环依赖没被LangGraph识别到，我之前就是两个tool互相调对方的callback，表面看是DAG实际成环了。

我之前用LangGraph也遇到过类似的死等，后来发现多半不是图结构的问题，而是子Agent内部在等某个外部资源或超时设置没配好。你可以试试给每个节点加个显式的超时和重试机制，同时在状态里塞个全局的heartbeat字段，这样能快速区分是卡在调度还是卡在某个Agent的IO上。另外检查下是不是多个Agent共享了同一个可变状态对象，LangGraph的StateGraph对并发写状态其实挺敏感的，建议把共享数据改成只读快照传参。

还有个小技巧，别光靠print，用langgraph的debug模式或者把每个节点的输入输出hash一下打进日志，能看出是哪一步的数据没更新导致下游不触发。我之前就是靠这个发现有个子Agent返回了空dict但没抛异常，上游就傻等它那个根本不存在的key。

这种死等我之前在LangGraph里也踩过，多半不是循环依赖的问题，而是你某个节点的条件边返回了不该返回的值，导致图直接停在那了。建议你先别盯着状态看，给每个节点加个入口日志和退出日志，再配合graph的debug模式，看最后停在哪条边上。另外子Agent之间如果非要有相互确认，最好拆成异步消息或者加个超时机制，别让它们在同一个同步流程里互锁。你试试把主管节点的interrupt逻辑检查一遍，我那次就是它吞了状态更新。

我之前用LangGraph也踩过这个坑，后来发现大部分“死等”其实不是图结构的问题，而是状态共享里的条件边没写好。你A等B、B等A这种，听起来像是两个节点都在等对方更新同一个state字段，但LangGraph的节点默认是同步推进的，如果某个节点没显式返回更新，下游就永远拿不到新值。我建议你先检查一下每个子Agent的返回dict，看看是不是漏了某个key，或者用了全局变量而不是state字段。另一个排查技巧是给每个节点加个超时或者手动打点，记录进入和退出的时间戳，这样能快速看出卡在哪个转移上。我之前还遇到过因为Recipient字段写错，导致消息发给了不存在的节点，结果日志不报错但就是不动。你可以在图定义里把每个边的条件函数单独打印出来，看它实际返回了什么，有时候是条件判断里用了旧状态。最后，如果实在查不出来，试着把任务拆小，先跑两个Agent的闭环，再加第三个，这样能定位是引入哪个节点后开始卡的。LangGraph本身对这种依赖支持是够的，但业务一复杂，节点间的隐式依赖很容易被忽略。

这题我熟，多半是图里条件边写死导致死锁，先检查supervisor的finish条件，别急着怀疑LangGraph。

把每个节点的输出都加上时间戳，卡住时看最后谁没返回，基本能定位是状态没更新还是调度没触发。

遇到过类似的，最后发现多半不是LangGraph的问题，而是你自己在状态里埋了雷。你这种A等B、B等A的情况，先别急着怀疑循环依赖支持，我猜大概率是节点里对共享状态的读写时机没控制好——比如某个节点提前读了还没被写入的key，然后直接返回了个空值，下游判断逻辑就卡在等待那个空值被填满，实际上根本没人再写它了。

我自己排查的时候有个笨办法，把每个节点的输入输出哈希一下打到日志里，不用print具体内容，只比对前后状态变化。如果某个节点输出和输入完全一致，基本就是它没被正确触发或者内部逻辑自己短路了。另外你检查下图的边是不是用了条件路由，有时候路由函数返回的分支名和实际节点名对不上，LangGraph不会报错，但会静默地不执行任何节点，看起来就像死等。

关于状态管理，我强烈建议你给所有共享字段加个版本号或者时间戳，哪怕只是个int自增。这样你在日志里能清楚看到谁在什么时候改过这个值，卡住的时候直接查最后修改者是谁，比瞎猜快得多。还有个小坑，如果你用了Send API做动态分支，多个Agent并发写同一个状态字段时会互相覆盖，但不会报错，这种死等最隐蔽。

Graph本身的设计我倒觉得不用太担心，LangGraph对循环是有支持的，但你需要显式设置max_iterations，不然它可能一直在循环里转但不报错。你可以先给整个图加个超时中断，卡住时把graph的状态dump出来，看看每个节点实际处于什么状态，是pending还是completed，这比看日志直观多了。

这种死等大概率是图结构里有环，LangGraph 对循环依赖不是不支持，而是你得自己保证每个节点都有明确的退出条件。我之前也踩过，表面看是 A 等 B、B 等 A，实际上是某个子 Agent 的输出没写进共享 state，导致下游节点一直拿不到触发条件。建议先把 graph 的边画出来，重点看有没有节点既在等消息又负责发消息，这种最容易互锁。排查时可以给每个节点入口打时间戳日志，卡住时看最后停在哪个节点，比单纯 print 状态快很多。

这种循环等待我踩过，十有八九不是LangGraph的锅，而是图里出现了隐式的环。你描述的场景很典型：A等B、B等A，本质上说明你的状态机里有一条没有显式声明的反向依赖，LangGraph只会按你给的边调度，它不会帮你检测语义上的死锁。可以去把每个子Agent的输入依赖列出来，画成有向图，八成能看到一个环。

排查上我一般会做两件事：一是给每个节点的进入和退出都打上带时间戳和状态快照的日志，卡住的时候看最后谁进没出，基本就能定位；二是把递归限制调低，比如设成10，一旦超了直接抛异常，比干等强多了。另外检查下有没有节点在等一个永远不会被写入的state字段，这种最容易被忽略。

还有个坑是条件边，如果路由函数返回的key和映射里的对不上，LangGraph可能默默走不到任何分支，表现就是卡住。建议在路由函数里加断言，把返回值打印出来确认。主管Agent那块也要注意，如果它负责分发任务但自己又在等子Agent的结果做汇总，很容易形成环，最好把调度和汇总拆成两个独立节点。

实在不行就上LangSmith或者自己包一层trace，把每步的state diff打出来，比print高效太多。图设计上，尽量保证依赖是单向的DAG，真要循环也得有明确的终止条件，别让Agent之间互相“确认”来“确认”去。