Agent调用流程深度拆解：从ReAct循环到LangGraph状态机编排

1. 从一个真实困惑说起：Agent 调用流程到底难在哪

很多人第一次接触 Agent 开发，脑子里想的都是"让大模型自己决定调什么工具、自己完成任务"，听起来很酷。但真正动手写第一版代码的时候，十有八九会卡在同一个地方：流程到底怎么串起来。模型输出了一段文本，说它想调用某个工具，然后呢？谁来执行？执行完的结果怎么塞回去？塞回去之后模型还会不会再调一次？如果它一直循环调用同一个工具怎么办？如果它中途需要人确认一下怎么办？

这些问题看起来零散，其实都指向同一个核心概念——Agent 调用流程。它不是一个 API，也不是一个类，而是一整套"模型思考、工具执行、结果回灌、循环推进"的编排机制。你用的框架无论是 LangChain、LangGraph 还是自己手搓，本质上都在解决这套流程的建模问题。

我见过太多项目，Demo 阶段跑得挺欢，一上真实场景就崩：要么是工具调用死循环把 token 烧光，要么是中间某一步报错整个流程直接挂掉，要么是需要人工介入的时候发现根本没有"暂停"这个状态。归根结底，是开发者对调用流程的理解停留在"能跑就行"，没有真正拆解过它的状态机本质。

这篇内容我打算把 Agent 调用流程从里到外讲透。不是那种"三步教你搭一个 Agent"的速成教程，而是从流程建模、状态管理、工具调度、中断恢复、并发控制这几个维度，把每个环节为什么这么设计、实际写的时候会踩什么坑，一条条摊开讲。适合已经跑通过最简 Demo、但想让 Agent 真正"下地干活"的开发者。如果你还在纠结 LangChain 和 LangGraph 选哪个，看完应该会有自己的判断。

2. 拆开看：一次完整的 Agent 调用到底经历了什么

2.1 最朴素的循环：Reason 与 Act 的交替

抛开所有框架，一个 Agent 调用流程最原始的形态就是一个 while 循环。核心逻辑可以用伪代码表达：

while not done: response = llm.invoke(messages) if response.has_tool_call: result = execute_tool(response.tool_call) messages.append(result) else: done = True

这就是经典的ReAct 模式（Reasoning + Acting）。模型先"想"（推理当前该做什么），然后"做"（调用工具），拿到结果后再"想"，直到它认为任务完成，输出最终答案。

这个循环看起来简单，但每一轮都涉及几个关键决策点。第一，模型怎么知道有哪些工具可用？靠的是把工具的描述（名称、参数 schema、功能说明）作为上下文注入到 prompt 里。第二，模型输出的工具调用请求怎么解析？早期靠正则匹配文本，现在主流模型都支持结构化的 function calling，直接返回 JSON 格式的调用意图。第三，工具执行结果怎么回灌？必须以特定角色（通常是 tool 角色）的消息追加到对话历史里，模型才能"看到"执行结果。

我实测下来，这个最朴素的循环在单工具、短链路的场景下完全够用。但一旦工具数量超过五六个，或者任务需要多步依赖（第二步的参数依赖第一步的结果），裸循环就会暴露问题：上下文越来越长、模型开始"忘记"之前的工具返回、错误处理全靠 try-except 硬扛。

2.2 状态机视角：为什么说 Agent 本质是一个图

把上面的循环换个角度看，它其实是一个状态机。每个节点是一个处理步骤（调用模型、执行工具、判断是否结束），边是状态转移条件。这个视角的转变非常关键，因为它直接决定了你能不能优雅地处理分支、循环、中断这些复杂逻辑。

LangGraph 就是把这个视角落地的产物。它让你用"节点 + 边"的方式显式定义流程：模型调用是一个节点，工具执行是一个节点，条件判断是一条条件边。这样做的好处是流程变得可观测、可干预、可持久化。你可以随时知道当前卡在哪个节点，可以在任意节点之间插入检查点，可以在某个节点前暂停等待人工输入。

对比一下 LangChain 的 AgentExecutor，它把整个循环封装成一个黑盒，你只能通过回调（callback）去"偷看"内部状态，想在中途插入自定义逻辑非常别扭。而 LangGraph 把循环拆开摊在你面前，每个环节你都能插手。这就是为什么现在做复杂 Agent，大家越来越倾向于用图的方式编排。

2.3 消息列表的膨胀问题与上下文管理

不管用什么框架，对话历史（messages）都是会不断增长的。每一轮工具调用都会往里面追加至少两条消息：模型的调用请求、工具的执行结果。一个稍微复杂点的任务跑十几轮，消息列表就能轻松突破几千 token。

这里有个很多人忽略的细节：工具返回的结果往往非常冗长。比如你调一个搜索工具，返回的是整页 HTML 或者一大段 JSON，直接塞进上下文，既浪费 token 又干扰模型判断。我的做法是在工具执行层做一次"结果压缩"，只提取模型真正需要的字段，或者对长文本做摘要后再回灌。

另一个坑是历史消息的裁剪策略。有些开发者图省事，直接保留最近 N 轮，结果模型丢失了早期的关键信息（比如用户最初设定的约束条件）。更稳妥的做法是保留系统提示 + 首轮用户输入 + 最近若干轮，中间的历史用摘要替代。LangGraph 里可以通过自定义 reducer 函数来控制状态如何合并，这一点后面会展开讲。

3. 工具调用这一环：从模型意图到真实执行

3.1 模型是怎么"决定"调用工具的

很多人以为模型真的在"调用"工具，其实模型做的事情只有一件：输出一段结构化的文本，表达它想调用哪个工具、传什么参数。真正的执行是框架层干的。理解这一点很重要，因为它意味着工具调用的可靠性取决于两件事：模型能不能正确理解工具描述，以及框架能不能正确解析模型输出。

工具描述（tool schema）的写法直接决定调用准确率。我踩过的坑包括：参数名用了模型不熟悉的缩写、描述里没写清楚参数的取值范围、多个工具功能重叠导致模型选错。一个实用的经验是，工具描述要像写给一个新同事看的说明书，说清楚这个工具干什么、什么时候用、每个参数是什么含义、有没有默认值。别指望模型能"猜"出你的意图。

结构化输出方面，现在主流模型都支持 function calling 或 tool use 协议，返回的是标准的 JSON。但不同厂商的格式有细微差异，LangChain 这类框架帮你做了适配层，统一成tool_calls字段。如果你自己直接调 API，一定要仔细读对应厂商的文档，别想当然。

3.2 并行工具调用：省时间但也埋雷

现代模型支持一次返回多个工具调用请求，也就是并行调用。比如用户问"北京和上海今天天气怎么样"，模型可以一次性发出两个天气查询请求，框架并行执行后一起回灌。这能显著缩短响应时间。

但并行调用有几个坑。第一，工具之间可能有依赖，如果第二个工具的参数依赖第一个工具的结果，就不能并行，必须串行。模型有时候判断不准，会错误地并行发出有依赖的调用，导致第二个工具拿到空参数。第二，并行执行的结果顺序要处理好，回灌给模型时必须和请求的顺序对应，否则模型会张冠李戴。第三，部分失败的处理，如果三个并行调用里有一个失败了，是整体重试还是只重试失败的那个？这些都需要在流程设计时想清楚。

我的建议是，对于有明确依赖关系的工具链，在工具描述里写清楚"此工具依赖 XX 工具的输出"，引导模型串行调用。同时在框架层做好结果顺序的校验。

3.3 工具执行失败的兜底设计

工具执行失败是常态，不是异常。网络超时、参数格式错误、外部服务限流，任何一种都可能发生。如果每次失败都直接抛异常终止整个流程，Agent 的可用性会非常差。

正确的做法是把失败也当作一种正常的工具返回。捕获异常后，把错误信息包装成工具结果回灌给模型，让模型自己决定是重试、换个工具、还是告诉用户做不到。这样 Agent 就有了"自我修复"的能力。

但要注意，不能让模型无限重试。我一般会设置一个单工具最大重试次数（比如 3 次），超过就强制中断并返回错误。LangGraph 里可以通过状态里的计数器来实现，每次进入工具节点时检查计数，超限就走异常分支。

def should_retry(state): if state["retry_count"] >= 3: return "give_up" return "retry"

这种条件边的设计，就是把"重试策略"从代码逻辑变成了流程的一部分，清晰且可调。

4. 中断与恢复：让 Agent 学会"停下来等人"

4.1 为什么需要中断：不是所有操作都能自动执行

Agent 自动化程度越高，风险越大。想象一个能操作数据库的 Agent，如果它自动执行了一条DELETE语句而没人确认，后果不堪设想。所以在关键操作前暂停，等待人工确认，是生产级 Agent 的必备能力。

这就是 LangGraph 里interrupt机制要解决的问题。它允许你在流程的某个节点前设置一个中断点，执行到这里时流程挂起，把当前状态保存下来，等待外部输入后再继续。这个"外部输入"可以是人的确认、可以是另一个系统的回调、也可以是定时任务。

中断的本质是状态的持久化与恢复。流程挂起时，整个状态（包括消息历史、中间变量、当前节点位置）都要被序列化存储；恢复时再反序列化，从断点继续。这就要求你的状态必须是可序列化的，别往状态里塞数据库连接、文件句柄这类东西。

4.2 interrupt 与 Command 的配合逻辑

LangGraph 的中断恢复靠一对机制配合：interrupt负责在节点内抛出中断信号，Command负责在恢复时携带数据重新进入流程。

具体来说，在节点函数里调用interrupt(payload)，流程会在这里暂停，payload是给外部看的提示信息（比如"即将执行删除操作，是否确认"）。外部拿到这个信号后，做决策，然后通过Command(resume=value)把决策结果传回去，流程从断点继续，interrupt的返回值就是value。

from langgraph.types import interrupt, Command def risky_operation(state): approval = interrupt({"question": "确认执行删除?", "target": state["target"]}) if approval == "yes": return {"result": do_delete(state["target"])} return {"result": "cancelled"}

这里有个容易搞混的点：interrupt在恢复后会重新执行整个节点函数，而不是从interrupt那一行继续。所以interrupt之前的代码会被再跑一遍。如果你的节点里有副作用操作（比如写日志、发请求），要确保它们在interrupt之后，或者做好幂等处理。这个坑我第一次用的时候踩得很结实，日志里出现了重复记录，排查了半天才反应过来。

4.3 恢复时的状态一致性怎么保证

中断恢复最容易出问题的地方是状态不一致。流程挂起期间，外部世界可能已经变了：数据库里的记录被删了、文件被改了、另一个流程修改了共享状态。恢复后如果直接按旧状态继续，很可能出错。

我的做法是在恢复时做一次状态校验。在Command里不仅传决策结果，还传一个版本号或者时间戳，恢复后先校验状态是否还有效，无效就重新走一遍前置流程。另外，对于长时间挂起的流程（比如等人工审批等了好几天），要设置过期机制，超时自动作废，避免僵尸流程堆积。

还有一点，中断点的设计要尽量靠后。把能自动做的都做完，只在真正需要人决策的那一步停。如果中断点设得太靠前，人工确认后还要跑一大堆流程，等待体验很差。

5. 并发场景下 Agent 调用流程的稳定性设计

5.1 多请求并发时状态如何隔离

单机跑一个 Agent 和同时跑一百个 Agent，是完全不同的两件事。并发场景下第一个要解决的就是状态隔离。每个请求必须有自己独立的状态空间，不能互相污染。

在 LangGraph 里，每次调用invoke或stream时传入的config里的thread_id就是隔离的关键。不同的thread_id对应不同的会话状态，框架会自动帮你隔离。如果你用的是自己手搓的循环，那就要确保每次请求的 messages 列表是独立创建的，别用全局变量。

我见过一个典型的错误：把工具实例或者状态对象定义成模块级全局变量，结果多个并发请求共享同一个状态，A 用户的对话历史跑到了 B 用户的上下文里。这种 bug 在低并发时根本发现不了，一上量就炸。

5.2 工具层的限流与超时控制

并发一高，工具层就成了瓶颈。外部 API 有 QPS 限制，数据库连接池有上限，文件系统有锁竞争。如果 Agent 流程不加控制地并发调用工具，很容易把下游打挂。

必须在工具执行层加限流和超时。限流可以用信号量或者令牌桶，控制同时执行的工具调用数量。超时则是给每个工具调用设置一个最大执行时间，超时就走失败分支，别让一个卡住的调用拖垮整个流程。

import asyncio semaphore = asyncio.Semaphore(10) # 最多 10 个并发工具调用 async def execute_with_limit(tool, args): async with semaphore: return await asyncio.wait_for(tool.ainvoke(args), timeout=30)

超时时间设多少合适？我的经验是根据工具性质分档：本地计算类 5 秒，外部 API 类 30 秒，涉及大文件处理或复杂查询的 60 秒。别一刀切设成很大，那样等于没设。

5.3 长流程的断点续跑与幂等

并发场景下还有个隐蔽的问题：流程执行到一半，服务重启了怎么办。如果状态没有持久化，重启后所有进行中的流程全部丢失，用户得从头再来。

LangGraph 提供了 checkpointer 机制，可以把每一步的状态存到数据库（比如 Postgres、SQLite）。这样即使服务重启，也能从最后一个检查点恢复。但要注意，恢复后的操作必须幂等。比如某个工具已经执行过了，恢复后不能重复执行。解决办法是在状态里记录"已完成的步骤"，恢复时跳过已完成的。

幂等设计说起来简单，做起来要考虑很多细节。比如工具调用有副作用（发了邮件、扣了款），恢复时怎么判断这个副作用是否已经发生？我的做法是给每个有副作用的操作分配一个唯一 ID，执行前先查这个 ID 是否已处理过，处理过就直接返回缓存结果。这套机制虽然增加了复杂度，但对于生产级 Agent 是必须的。

6. 框架选型：LangChain 与 LangGraph 在调用流程上的分野

6.1 LangChain AgentExecutor 的便利与局限

LangChain 的 AgentExecutor 是很多人入门 Agent 的第一站。它把"模型调用 + 工具执行 + 循环"打包成一个执行器，你只需要提供模型、工具列表和提示词，它就能跑起来。上手成本极低，适合快速验证想法。

但它的局限也很明显。第一，流程是黑盒，你无法精细控制每一步之间的转移逻辑。第二，中断能力弱，想在中间暂停等人工确认，得绕很多弯。第三，状态管理不透明，出问题的时候很难定位是哪一步的状态出了偏差。第四，并发和持久化支持有限，做生产级应用力不从心。

我的判断是，AgentExecutor 适合做 Demo 和简单任务，一旦任务复杂度上来，或者需要人工介入、需要持久化、需要精细的错误处理，就该考虑迁移到 LangGraph 了。

6.2 LangGraph 的图编排优势在哪

LangGraph 的核心价值在于把流程的控制权交还给开发者。你用节点和边显式定义流程，每个节点的输入输出、每条边的转移条件都清清楚楚。这种显式建模带来的好处是多方面的。

调试的时候，你能精确知道流程卡在哪个节点、状态是什么。扩展的时候，加一个新步骤就是加一个节点，不影响其他部分。做中断的时候，interrupt和Command是原生支持的，不用自己造轮子。做持久化的时候，checkpointer 直接对接数据库。做并发的时候，thread_id天然隔离。

代价是学习曲线更陡。你需要理解状态、节点、边、检查点这些概念，需要自己设计状态结构，需要处理 reducer 的合并逻辑。但这点投入在复杂场景下完全值得。

6.3 什么场景该用哪个：一份决策参考

这张表不是绝对的，但能帮你快速定位。我的建议是，哪怕最终用 LangGraph，也先手搓一遍裸循环，把 ReAct 的每一步都亲手实现一次。这样你再看框架的封装，就知道它到底帮你做了什么，出问题的时候也知道去哪找。

7. 几个真实踩过的坑与排查思路

7.1 工具调用死循环：模型为什么一直调同一个工具

死循环是 Agent 最常见的故障。表现是模型反复调用同一个工具，每次都拿到相似的结果，但就是不结束。原因通常有三种：工具返回的结果没有让模型获得新信息、工具描述让模型误以为必须调用、或者提示词里没有明确的终止条件。

排查的时候，我会先把完整的消息历史打出来，看模型每一轮看到了什么、输出了什么。如果发现工具返回的结果和上一轮几乎一样，那就是工具本身没提供有效信息，需要改工具逻辑。如果模型在提示词里被要求"必须使用工具"，那就要放宽这个约束，允许它直接回答。

兜底方案是设置最大迭代次数。LangGraph 里可以在状态里加一个计数器，每轮递增，超过阈值就强制走结束分支。这个阈值设多少？我的经验是 10 到 15 轮，大部分正常任务都能在这个范围内完成，超过的基本都是出问题了。

7.2 状态丢失：恢复后模型"失忆"了

用 checkpointer 做持久化的时候，遇到过恢复后模型完全不记得之前发生了什么。排查发现是状态序列化时漏了字段。LangGraph 的状态是通过 reducer 合并的，如果你自定义了状态结构但没正确定义 reducer，某些字段在保存或恢复时会被丢弃。

解决办法是仔细检查状态定义，确保每个字段都有明确的合并策略。对于消息列表，用add_messages这个内置 reducer；对于普通字段，用覆盖式 reducer；对于需要累加的计数器，用求和 reducer。别偷懒用默认行为，默认行为往往不是你想要的。

7.3 中断恢复后重复执行：副作用操作的幂等处理

前面提过interrupt恢复会重跑整个节点，这个特性导致的重复执行问题非常隐蔽。我遇到过一次，恢复后给用户发了两封确认邮件。排查后发现是发邮件的代码写在了interrupt之前。

修复方式有两种：一是把副作用操作移到interrupt之后；二是给副作用操作加幂等标记，执行前先检查是否已执行。我倾向于两者结合，既调整代码顺序，又加幂等保护，双保险。

7.4 并发下的状态串扰：thread_id 用错导致的诡异 bug

有个线上问题困扰了我很久：偶尔有用户反馈看到了别人的对话内容。排查后发现是并发请求时thread_id生成逻辑有 bug，极端情况下两个请求拿到了相同的 ID，状态就串了。

修复很简单，把thread_id的生成改成 UUID 或者"用户ID + 会话ID + 时间戳"的组合，确保全局唯一。但这个 bug 给我的教训是，并发场景下任何共享标识符都要严格保证唯一性，别用自增 ID 或者时间戳这种可能碰撞的方案。

8. 把调用流程做扎实的几个实用建议

如果你正在做 Agent 项目，想让调用流程真正扛得住真实场景，我有几条从实践中总结的建议。

第一，先把流程画出来再写代码。用纸笔或者白板，把模型节点、工具节点、条件分支、中断点都画清楚。流程想明白了，代码就是翻译。我见过太多人上来就写代码，写到一半发现流程有漏洞，推倒重来。

第二，状态设计要克制。别把什么数据都往状态里塞，只放流程推进必需的信息。状态越简单，序列化越容易，调试越清晰。临时数据用局部变量，别污染全局状态。

第三，每个工具都要有超时和重试。这是生产级的基本要求，别指望外部服务永远稳定。超时时间根据工具性质设定，重试次数控制在 3 次以内，超过就上报错误。

第四，中断点设计要慎重。只在真正需要人决策的地方设中断，且中断点尽量靠后。中断太频繁会严重影响自动化体验，中断太靠前会让用户等太久。

第五，日志要打全。每一轮模型输入输出、每一次工具调用参数和结果、每一个状态转移，都要有日志。出问题的时候，日志是你唯一的线索。我一般会把日志按thread_id聚合，方便追踪单个会话的完整链路。

第六，压测要趁早。别等上线了才发现并发扛不住。本地用工具模拟几十上百个并发请求，观察状态隔离、工具限流、内存占用这些指标。早发现早修复，成本低得多。

Agent 调用流程这个东西，入门容易精通难。跑通 Demo 可能只需要半小时，但要做到生产可用，需要把状态管理、错误处理、中断恢复、并发控制每一个环节都打磨到位。这个过程没有捷径，只能一个坑一个坑地踩过去。但每踩一个坑，你对整个系统的理解就深一层，下次遇到类似问题就能快速定位。这大概就是做 Agent 开发最有意思的地方——它逼着你把分布式系统、状态机、并发编程这些知识真正用起来，而不是停留在纸面上。