1. 先看一个让我彻底转向 ReAct 的真实场景大概一年前我在做某个模拟项目 X 的智能客服模块。需求本身不复杂用户问天气、问时间、查订单状态模型先理解意图再调用接口返回结果。开始的方案很简单——把用户问题和候选工具描述拼进 Prompt让模型直接输出一段 JSON 格式的“意图参数”代码拿到 JSON 后去调对应的 API。单看意图识别准确率还行问题出在“多跳”场景。有一次用户问“明天上午从公司去机场路上会下雨吗”这个问题要拆成至少四步先定位“公司”的坐标再查“明天上午”该坐标的天气同时要估算“公司到机场”的行车时间最后把“出发时间 通勤耗时”和“降雨时段”对齐才能给出答案。我当时那个单轮 JSON 方案直接崩了模型把“公司”猜成某个地址通勤时间也没算进去回答完全不可用。后来我把这套流程改成 ReAct 思维范式同样是这个例子模型先生成一句内部推理——“我需要先确定公司坐标再结合明天上午的天气和通勤时间综合判断”随后调用地理编码工具获取坐标拿到坐标后再调天气接口和路线规划接口最后基于全部返回结果组织回答。整个过程模型交替进行“思考”和“行动”每一步的行动结果都会作为下一步推理的依据。效果提升非常明显多轮依赖的复杂问题终于被真正解决掉了。如果你也在做 Agent 相关的开发或者你正在被“模型不会按步骤调工具”这个问题折腾这篇文章应该能帮你省下不少试错时间。我会把 ReAct 的循环结构、Prompt 设计方式、工具调用时的常见翻车点、以及和 CoT、Plan-and-Execute 等范式的对比一次讲透最后附上我的调试心法。2. 拆开 ReAct 循环Think推理、Act行动、Observe观察这三步到底在做什么ReAct 这个名字是 Reasoning Acting 的合成词核心思想一句话就能说清让模型在解决问题时既动脑又动手且动手的结果会反哺动脑。它不是让模型一次性想完再干而是“想一步、做一步、看结果、再想下一步”的循环。我把这个循环拆成三个环节分别来看它们各自承担的职责。2.1 Think把“下一步需要什么”想明白很多人误以为 Think 就是让模型“多想想”其实在 ReAct 里Think 有一个非常具体的任务识别当前的信息缺口。也就是说模型要回答的不是“答案是什么”而是“要得到答案我现在还缺哪块信息”。还拿刚才那个“公司去机场下雨吗”的例子。模型的第一轮 Think 可能是这样Thought: 我不知道用户公司的具体位置也不知道明天上午的天气和通勤时间。 我需要先获取公司的坐标再查询天气和路线信息。这段思考里没有直接回答用户问题而是列出了一个“待办清单”。这种表达方式有两个实际作用。第一它把复杂任务拆成了可以被工具逐一满足的子问题第二它给后续的 Act 提供了明确依据——你接下来调工具不是随机调而是因为 Think 里说了“需要坐标”。我在实际项目中习惯在 Prompt 里明确写一句“先想清楚缺少哪些关键信息再选择工具”这会显著减少模型跳过推理直接乱调工具的情况。有些模型在 Few-shot 示例不足时容易跳过 Think 直接输出 Action后面你会发现整个链路很快就歪掉。2.2 Act调用工具执行一个可被观察的动作Think 只回答了“缺什么”Act 负责“补什么”。这一步是 ReAct 和纯 CoT思维链最大的分水岭——纯 CoT 只在模型内部进行文字推理推理完直接输出答案ReAct 则把推理的中间结论外化为具体动作比如调用 API、执行代码、查数据库、发请求。工具返回的结果就是动作的效果。这里有一个关键点一次 Act 最好只做一件事。我见过很多新手把多个动作塞进一个 Action 里比如“查询天气并计算通勤时间”结果工具定义复杂、出错后难以定位模型也因为反馈信息过载而不知道下一步该做什么。正确的做法是让一次 Act 足够原子化Action: geocode(query某公司) Action Input: {address: 用户文本中的公司名}这一步返回经纬度下一步再根据经纬度查天气再下一步查路线。每一步都是一个小而清晰的动作。工程上这叫“一个工具调用只解决一个信息缺口”在维护和排查时你会感激这个原则。2.3 Observe把工具结果转成下一轮思考的输入Observe 是 ReAct 循环里最容易被忽略、但决定成败的一环。很多 Agent 框架跑飞不是模型想错了也不是工具调错了而是观察结果没有被正确地送回推理上下文。举个例子天气接口返回了一长串 JSON里面包含湿度、风速、气压、降水概率、紫外线指数等十几个字段。如果你把整个 JSON 原封不动塞回上下文模型在下一步 Think 时容易被无关字段干扰甚至开始“脑补”字段之间的因果关系。正确的做法是设计一个轻量化的观察文本只保留和当前任务相关的核心信息Observation: 地点某公司(经度xx, 纬度xx)明天上午天气小雨 降水概率85%最低温18℃最高温22℃。这一步等价于给模型做了一次“信息压缩”。在我自己的项目里我通常会为每个工具写一个简短的“结果摘要函数”把原始返回值转成一两行文字再交给模型。模型的上下文窗口是有限的Observe 环节的压缩能力直接决定了整个 Agent 能连续思考多少轮而不被塞爆。这三个环节串起来就是完整循环Thought → Action → Observation → Thought → Action → Observation → ... → Final Answer不需要一步到位不需要提前编排所有步骤模型边走边看边调整。这就是 ReAct 最核心的思维方式用外部反馈来校准内部推理。3. 工具调用是最容易翻车的地方工具定义、结果截断与幻觉控制ReAct 的循环结构说起来简单真正写代码时你会发现 80% 的调试时间都花在“工具调用”这个环节上。这里我按踩坑频率从高到低讲三个最典型的坑。3.1 工具描述写得太含糊模型根本不知道什么时候该调它工具的描述文本其实就是在给模型写“使用说明书”。如果你把函数名和参数列表塞给模型却没说清楚“这个工具适合解决什么问题”模型就很容易在错误的时候调用它。我早期犯过的一个错误是给天气查询工具这样描述get_weather(latitude: float, longitude: float)看起来没毛病但模型经常在用户只问“现在几点”的时候也去查天气。后来我把描述改成get_weather(latitude, longitude, date) 获取指定经纬度和日期的天气信息包含温度、降水、风力等。 仅当用户询问天气、降雨、温度、出行是否需要带伞时使用。加上最后一句“仅当……时使用”模型误调用的概率立刻下降了一大截。这个经验的本质是工具描述里写清楚触发条件比写清楚参数类型更重要。参数类型模型能从函数签名推断而触发条件只能靠描述。3.2 工具返回结果太长把上下文窗口和模型注意力一起撑爆工具返回结果无论是 JSON 还是长文本都是极端“话痨”的。拿数据库查询举例你让模型执行一句 SELECT它可能返回 200 行记录每行有 20 个字段。如果你把这些全部原样塞给模型接下来的 Think 几乎一定会出问题——模型被海量无关信息淹没找不准和当前子问题相关的部分。我的做法是给每个工具设计一个结果处理函数输出尽量控制在 200 token 以内。核心原则三条只保留和任务直接相关的字段能用一句话概括的就不要列清单数值类的信息给出单位和范围比如刚才说的 SELECT 查询返回 200 行我会让结果处理函数先做一次聚合输出统计摘要只有当模型明确需要明细时才再查一次。这个过程其实是把“Observe”环节的压缩从 Prompt 层面下沉到了代码层面让模型永远只看到高信噪比的观察结果。3.3 模型的 Action Input 会编造参数这是最大的隐蔽坑幻觉不只是发生在最终回答里也会发生在行动参数里。有一次用户问“北京明天会不会下雪”我的模型自动填写了经纬度参数但它填的经纬度根本不是北京的坐标而是一个南方城市的坐标。观察结果回来之后模型还一本正经地说“明天该地区有小雪”——它完全没意识到坐标不对因为只看到了一段数值是“对的格式”的返回结果。从那以后我在所有涉及外部数据的工具调用前都加了一道参数校验1. 参数必须来自已有信息不能凭空生成 2. 如果用户没有提供地理位置信息必须先调用地理编码工具获取 3. 不允许在 Action Input 中填写未经确认的数值这个方法的效果非常明显。模型被迫把“获取坐标”和“使用坐标”拆成两步反而让链路更清晰了。很多 Agent 出现“一本正经胡说八道”的问题根源往往不是最终回答环节的幻觉而是行动参数环节就已经产生了幻觉后面所有的推理都建立在错误地基上。4. 让循环停在该停的地方终止条件、最大步数与过程评分ReAct 循环如果设计得不好最直观的灾难就是“停不下来”。模型会一直 Think → Act → Observe像一个在迷宫里反复绕圈的人。这个问题的根源往往不是模型笨而是你没有给它清晰的终止条件。终止条件的设计要分两层一是模型层面的结束信号二是代码层面的硬性限制。4.1 让模型自己判断“可以收尾了”在 Prompt 里我建议明确告诉模型当你积累了足够回答用户问题的信息或者你确定无法继续推进时必须输出 Final Answer而不是继续调用工具。一个有效的表达方式如果用户的问题已经可以被当前掌握的信息回答立即输出 Final Answer。 不要为了调用工具而调用工具。只有在缺少关键信息时才继续行动。这个指令单独看似乎很普通但配合 Few-shot 示例效果立竿见影。因为 ReAct 循环有“惯性”模型在前几轮使用了工具会倾向于继续使用工具哪怕已经不需要了。你需要在指令里给模型一个“踩刹车”的正当理由。4.2 代码层面永远要有最大步数兜底即使 Prompt 写得再清楚模型也可能因为上下文理解偏差而进入死循环。这时候你唯一能依赖的就是硬编码的步数上限。我在实践中会把最大步数设置成和任务复杂度相关的数值简单任务 35 步复杂任务 812 步。到达上限时直接截断循环返回当前已收集信息的总结并向用户提示“未能完全满足问题要求”。我见过有人把最大步数设成 20、30觉得“给模型更多机会”但实际上步数越多偏离用户原始意图的风险越大。模型的每一步行动都有误差误差会累积。宁可让它更早收尾给出部分答案也好过绕了十几步得到一个越来越偏的结论。4.3 用“中间奖励”判断每一步的质量在开发阶段我习惯在循环里加一个轻量级的“过程评分”逻辑用来监控每一步 Think 的质量。具体做法是设定几个简单的评分规则比如本次 Action 是否和上一个 Think 中提到的信息缺口一致本次观察结果是否被下一步 Think 引用连续两次 Action 是否指向同一个信息缺口如果是指向了同一个说明可能陷入了原地踏步这套评分不参与模型推理只用于日志输出。但它在调试阶段非常有用——我只需要扫一遍每轮的评分就能快速定位是哪一步开始跑偏的。有一次某个 Agent 频繁返回错误答案我根据评分发现模型在第 2 轮就开始调一个无关工具后面所有步骤都在错误方向上“正确执行”。这个过程单看最终结果很难察觉但过程评分把问题暴露得一清二楚。5. ReAct 之外的路和纯 CoT、Plan-and-Execute、Reflexion 一起看才知道什么时候该选谁ReAct 是 Agent 思维范式的地基但不是万能药。我在实际项目里会有意识地根据任务类型选择不同范式这里把常见几种放在一起对比帮你建立选型直觉。5.1 纯 CoT只在脑子里推演不接触外部世界纯 CoTChain-of-Thought就是让模型“把思路写出来再回答”。它适合那些不依赖外部信息的任务比如数学计算、逻辑推理、文本总结。ReAct 比 CoT 强的部分在于外部反馈校准但如果任务本身不需要外部信息ReAct 的额外动作反而会引入噪音。一个简单的判断方法如果所有信息都在 Prompt 里用 CoT如果答案需要外部数据支持用 ReAct。比如“计算 1234 乘以 5678”用 CoT比如“查询某订单的物流状态并预估送达时间”用 ReAct。5.2 Plan-and-Execute先把步骤全想好再一步步执行Plan-and-Execute 是另一种重要范式模型先输出一个完整的执行计划然后按照计划依次执行中途不改变计划。它的优点是可解释性强、执行路径清晰缺点是无法根据中间结果调整计划。ReAct 和它的区别在于“计划是固定还是动态的”。ReAct 每轮都可以重新规划Plan-and-Execute 则在开始时一次规划完毕。我用一个容易理解的类比Plan-and-Execute 像按菜谱做菜严格按照步骤走ReAct 像老厨师炒菜边做边看火候调整。如果你的任务流程相对固定Plan-and-Execute 效率更高如果任务充满不确定性ReAct 鲁棒性更强。我自己的项目里经常是混合使用先用 Plan-and-Execute 生成一个粗粒度计划然后在每一步内部用 ReAct 处理子问题。5.3 Reflexion多了一步“复盘”适合复杂任务反复迭代Reflexion 是在 ReAct 基础之上增加“评估与反思”环节。它在循环结束后让模型回顾整个过程总结“哪里做错了”“下次哪里可以改进”然后将反思结果作为新的一轮循环的额外上下文。这个范式适合那些需要多轮试错的任务比如写代码调试、决策优化。但代价是 token 消耗显著上升循环次数也会增加。我在使用 Reflexion 时有一个很实际的建议不要每一轮都做完整反思只在失败后启动反思循环。成功路径上直接返回结果失败后再反思重试这样既保留了反思的好处又不会给每一次任务都增加额外开销。5.4 选型对比表范式核心特点适用场景主要短板纯 CoT仅文字推理无外部动作数学、逻辑题、纯文本任务无法获取外部信息错误无法被修正ReAct推理与动作交替动态规划需要调用工具、信息不完全的任务步数较多时可能发散token 消耗高Plan-and-Execute先规划后执行路径固定流程明确、步骤稳定的任务中途无法调整意外情况容错差Reflexion失败后反思并重试调试、优化、多轮试错循环次数多、成本高、需要额外设计评估器看完这个表你会发现ReAct 的定位非常清晰它是“外部世界不可预测”时最稳妥的默认选择。工程上有一个比较流行的判断标准如果工具调用的成功率低于 90%或者环境反馈噪声较高优先选择 ReAct如果每个工具都非常可靠流程完全确定Plan-and-Execute 的执行效率更高。6. 排错心法遇到循环、乱选工具、状态丢失时我通常怎么定位无论 ReAct 的架构设计得多好实际运行中你一定会遇到各种稀奇古怪的问题。这里我分享一套我自己的排查方法论按照“看日志 → 缩小范围 → 改设计”的顺序来。6.1 问题一Agent 陷入某个局部循环重复调用同一个工具这是最高频的问题。现象是模型连续三轮以上调用同一个工具且传入的参数几乎一致说明它“认为”自己还没有获得需要的信息但每次获得的结果又不足以让它重新规划。我的排查思路分三步。第一步检查工具返回的 Observation 是否真的被下一步 Think 理解。很多循环问题不是模型问题而是观测信息太模糊模型读完等于没读。把 Observation 写得更有信息量循环往往就消失了。第二步检查是不是 Think 阶段没有输出“新结论”。如果模型每轮都写“我还需要天气信息”但下一轮还是用同样的方式查同样的数据说明 Prompt 里缺少“基于已有信息重新评估缺口”的引导。第三步实在不行就启用步数上限和“重复动作检测”。如果检测到连续两次 Action 完全相同直接中断并在提示里让模型反思是不是工具返回的信息不满足需求。这个兜底逻辑不优雅但能防止生产环境的死循环拖垮整个任务。6.2 问题二模型选择了错误的工具但逻辑上看起来很“合理”这个坑隐蔽在模型每一步都有思考过程思考内容和 Action 也一致但方向从一开始就是错的。比如用户问“某本书的库存”模型却调用了一个天气工具——因为工具描述里的“获取外部信息”让模型误判了这个工具也能查库存。遇到这种情况我几乎 90% 会在工具描述里找到原因。工具描述越模糊模型的错误选择越频繁。排查办法是看日志里模型选用工具前的 Thought 内容它会告诉你模型是基于什么特征选择了这个工具。比如模型 thought 里写“用户需要外部数据我调用 weather 接口获取”那下次你在天气工具描述里明确写“本工具仅用于气象数据查询”。另一种做法是增加一个“工具选择澄清”环节当模型不确定选哪个工具时允许它先输出一个选择题给用户或给上级 Agent 确认。代价是多一轮交互但换来了确定性。6.3 问题三上下文越长模型越“失忆”这是所有长周期 Agent 的必经之痛。任务进行到第 10 轮时模型开始遗忘用户最初的需求或者忽略最早几轮工具返回的关键信息。我的应对手段是“显式记忆压缩”。每隔几轮我会将关键信息整理成一段 summary并把它放在上下文靠近开头的位置同时在 Prompt 里用明确的文字提醒模型“以下是你先前已确认的关键信息后续推理必须基于这些事实。” 这样即使早期信息被挤出注意力窗口模型依然能在重要位置看到提炼过的摘要。不过这个方案也有限制。summary 写太短会丢失细节写太长又起不到压缩作用。我的经验是把关键信息限制在 3 到 5 条每条不超过一句话。这样既保住了核心事实又不会给上下文增加太多负担。更激进的做法是引入外部记忆存储把历史完整轨迹放到向量数据库里只在需要时按相关性检索注入但这个方案复杂度高项目初期不建议上。6.4 一套可以复制到其他项目的调试模板最后分享一个我在调试 ReAct Agent 时固定使用的日志模板。每个循环都会输出一段结构化的 debug 日志[Step 1] Thought: ... Action: ... Action Input: ... Observation: ... Score: 1.0我会重点关注 Score过程评分下降的那一步然后用“如果我是模型我看到了这个 Observation我会怎么做”来推演基本上很快就能找到问题出在 Prompt、工具定义还是参数处理上。这套方法并不复杂但它要求你像审讯一样去审问每一轮循环的痕迹。Agent 的每个错误都不会无缘无故发生它一定是某个环节的信号没有被正确传递。最后的小建议如果你正准备在项目里引入 ReAct 思维范式我的建议是从一套最小化可运行的循环开始不要一上来就堆工具。先用两三个工具把循环跑通检查 Think 的质量、Observation 的传递、终止条件的触发再把工具逐步增加。过程中你会慢慢理解为什么 ReAct 会让模型变得更“靠谱”——不是因为它让模型更聪明了而是因为它给模型的每一步推理都接上了外部反馈让它有机会从错误中及时转向。踩过的坑多了之后你会意识到ReAct 真正难学的地方不在原理而在“放手”与“控制”的平衡既要给模型足够的行动自由去探索又要通过 Prompt、工具设计和终止条件给它画出清晰的边界。找到这个平衡点你的 Agent 才会真正像一个有判断力的助手而不是一个盲目调接口的脚本。