你有没有试过让大模型去干一件稍微带点操作步骤的活儿比如“把服务器上所有磁盘占用率超过80%的目录找出来然后按占用大小排个序再生成一份整改建议”。你可能会发现直接问一句模型能给你一份像模像样的报告但仔细一看很多数据是它编的因为它根本没碰过你的服务器。再比如“帮我把这批图片统一改成640x640顺便压缩到200KB以内”模型说得头头是道但它一张图都不会动。这就是当前对话式大模型的典型瓶颈它能推理但不能行动它能生成文本但不能获取真实世界的新信息。你问它知识性问题它靠训练时的记忆能答个大概你让它干需要实时数据、需要操作工具的活儿它就露馅了。ReAct框架就是冲着这个问题来的。它的核心思想非常朴素——让模型在一个循环里交替做四件事推理、行动、观察、反思直到把任务搞定为止。注意这不是简单的“模型调工具”而是一种结构化的决策循环。它把大模型从“一个回答问题的对话机器人”变成了“一个能拿着工具、边干边想的智能体”。这篇东西我自己调过不下几十个Agent项目从最初照着论文撸一个最简实现到后来在生产环境里跑真实任务踩过的坑可以绕会议室一圈。这篇文章就把这套框架的原理、细节、实操代码和坑位一次讲清楚。适合三种人看准备入门AI Agent的开发者、已经在用Agent但总感觉结果不稳的调参选手、以及想评估这套范式能不能落地到业务场景的技术负责人。1. 整体设计思路拆解ReAct到底在循环什么1.1 静态推理和动态行动的差别在哪先想一个很基础的场景你让一个模型回答“某公司最近发布的季度财报里面营收同比增长了多少”。如果模型没记住这个信息它会怎么办它可能会根据训练数据里的历史趋势猜一个数字然后一本正经地告诉你。这就是纯粹基于内部知识的“静态推理”业界管这种方法叫Chain-of-Thought也就是让模型一步一步想但每一步想的都是它记忆里的东西外部世界对它来说是关闭的。ReAct的突破在于它把“想”和“做”串在了一个循环里。模型每走一步不仅能输出一段“我打算怎么做”的文字还能输出一个“我要调用某个工具”的动作工具返回的结果会成为新的输入模型再基于这个新输入继续推理。这就像你让一个人去修水管光站在那儿想“可能是接头松了”是没有用的你必须动手拧一下接头看看还漏不漏水然后再决定下一步是换垫圈还是换整段管子。我在实际项目中见过最典型的例子一个运维问答机器人用纯对话方式时用户问“某服务的平均响应时间最近三天是多少”模型能编出一堆数字换成ReAct框架接上监控查询工具之后模型会先查最近三天的数据再根据真实返回结果去分析趋势准确性完全是两个量级。1.2 循环里的四步分别是什么ReAct整个循环可以拆成四个角色明确的部分缺一不可。第一个是推理。模型根据当前已知信息想清楚“我现在处于什么状态、离目标还有多远、这一步该干什么”。这一步的输出一般是自然语言它不需要很长但必须指向一个可执行的判断。第二个是行动。模型从预设好的工具列表里选一个填好参数然后执行。行动必须可被程序解析所以通常输出的是一个结构化格式比如JSON。第三个是观察。工具执行之后返回结果这个结果可能是文件内容、查询记录、数值、报错信息不管是什么它都会作为新一轮的输入补充进来。第四个是反思。模型对比观察结果和预期目标判断“这次行动有效吗方向对吗还有必要继续吗”然后据此生成新的推理进入下一轮循环。举个例子一个典型的循环轨迹长这样{ thought: 我需要先确认目标主机上当前nginx的版本才能判断是否存在需要修复的已知问题。, action: run_command, action_input: { command: nginx -v } }执行后返回{ observation: nginx version: nginx/1.18.0 }模型拿到这个观察结果进入反思“当前版本是1.18.0距离目标版本1.22.0还有差距下一步需要执行升级。”然后输出新一轮的推理和行动。这四步里最容易忽略的是“反思”。很多初版实现只做了“推理-行动-观察”三步发现模型经常在同一个错误方向上反复折腾。加了反思之后模型会主动纠偏比如“我刚才查了机器A但目标是机器B我选错了对象”然后下一步就换目标。这一步是整个循环从“机械执行”变成“智能体”的关键。1.3 两个反馈闭环的设计逻辑ReAct的循环里其实藏着两个不同粒度的闭环。第一个闭环是“行动-观察”微循环。这个循环通常发生在单个子任务内部模型调一个工具看结果再调一个工具再看结果直到这个子任务的数据收集完毕。比如要分析磁盘占用模型可能先执行df -h再执行du -sh /*再根据输出决定要不要深入某个目录。每一步都在微循环里快速修正。第二个闭环是“反思-规划”大循环。这个循环发生在更高层面模型通过反思发现整个方案走不通或者发现了新的约束条件于是调整整体策略。举个例子模型原本计划通过A工具拿数据但A工具返回了权限错误反思后它判断“这条路不可行先切换到B工具绕过或者让用户授权”这就是大循环在起作用。为什么要区分这两个闭环因为它们的触发频率不同、成本不同。微循环每轮都可能发生token消耗高但效果好大循环不需要每一步都触发只在关键节点比如一次行动失败、一个子任务完成、结果与预期偏差明显时才触发。很多框架实现里用“最大迭代次数”来限制微循环的规模用“反思触发条件”来控制大循环的频率两者配合才能既灵活又可控。2. 核心细节解析与实操要点2.1 提示词不是写一段话而是写一套协议ReAct的效果好坏有一半取决于提示词的质量。我见过最多的问题就是开发者把提示词写成一段“麻烦你认真一点、一步一步来、做完了检查一下”这种感性话模型确实会认真但不知道该按什么格式输出结果解析失败、循环直接卡死。正确的做法是设计一套“协议式”提示词至少包含三部分。第一部分是角色与目标说明告诉模型它是什么、要完成什么、边界在哪。第二部分是工具清单把每个工具的名字、用途、参数格式、返回内容说清楚。第三部分是输出格式约束明确要求模型每轮必须输出JSON且JSON里必须包含thought和action等固定字段。我常用的一个提示词模板长这样你是系统配置助手。你的任务是完成用户指定的配置变更或检查任务。 你可以使用以下工具 - get_host_info(host_id): 获取某台主机的详细配置信息。 - get_desired_config(service_name): 获取指定服务的目标配置标准。 - apply_config(host_id, config): 将一份配置应用到指定主机。 - verify_config(host_id): 验证指定主机是否满足目标配置标准。 你必须严格按以下JSON格式输出每次只输出一轮 {thought: 你对当前状态的分析和下一步计划, action: 工具名, action_input: {参数名: 参数值}} 当你判断任务已经完成时输出 {thought: 任务已完成, action: finish, action_input: {}}注意工具清单里每个工具的描述不能太含糊。比如“get_host_info(host_id): 获取主机信息”模型大概率不知道什么时候该用它写成“获取某台主机的详细配置信息包括操作系统版本、CPU核数、内存大小、磁盘分区及占用率用于判断主机是否满足目标配置要求”模型就清楚多了。工具描述本质上是给模型的“选择提示”描述越贴近真实业务场景模型选错工具的概率越低。2.2 工具注册与输出序列化为什么JSON不解析就想别往下走ReAct的动作输出必须被程序解析所以格式设计和解析稳定性是第一优先级。我强烈建议无论用哪种模型都强制输出JSON格式且字段固定。最稳的做法是在系统提示词里给一个成功示例和一个失败示例让模型照着写。工具侧同样要重视序列化设计。每个工具执行完必须返回一个能被模型读懂的结构化结果不能只是抛出一段异常堆栈。一个合理的做法是统一返回一个包含“status”和“data”的对象def run_command(command: str) - dict: try: result subprocess.run(command, shellTrue, capture_outputTrue, textTrue, timeout30) return { status: success if result.returncode 0 else error, data: result.stdout.strip()[:2000], error: result.stderr.strip()[:500] } except Exception as e: return { status: error, data: , error: str(e)[:500] }这个返回结构有两点考量。第一status字段让模型一眼知道这一轮行动成没成功不需要它去解析一堆输出文本里有没有“error”字样。第二data和error字段做了长度截断避免工具返回日志太长把上下文窗口撑爆。模型看到这种结构后续的反思环节会轻松很多因为它不需要自己判断“刚才那个输出到底有没有问题”状态字段已经替它判断了。我踩过一次很深的坑工具返回的日志有几十KB直接把整个上下文窗口塞满模型开始胡言乱语说“根据日志无法判断”。后来做了一层摘要只保留前2000字符和“ERROR”“WARN”关键行问题立刻消失。这类细节在Demo里不会暴露一上真实数据就会翻车。2.3 推理轨迹的结构化存储调试和复盘的命根子ReAct循环跑起来之后每一轮都会产生四类数据thought、action、action_input、observation。这些数据如果只打在控制台里调试时会非常痛苦。我建议从一开始就把轨迹落成结构化日志每轮一条记录字段至少包括字段类型说明stepint当前轮次timestampstring该轮触发时间thoughtstring模型的推理内容actionstring选用的工具名action_inputobject传给工具的参数observation_statusstring工具返回的状态如success/errorobservation_summarystring观察结果的摘要evaluationstring人工或规则评价该轮是否合理存储这套日志的价值在哪儿第一是问题复现用户报“Agent跑错了”你可以直接调出那一段轨迹看模型到底想了什么、调了什么工具、拿到了什么结果。第二是迭代优化你把这些日志攒够一百条自己通读一遍就会立刻发现高频错误点比如“模型总是把参数名写错”“模型在某个工具失败后不会换路”。第三是安全审计在正式环境里Agent的每一步操作都必须可追溯这套日志就是审计依据。我在项目里保存日志时还会额外记录每一轮的token消耗和耗时。ReAct循环是一个迭代过程如果不记录Token消耗月底结算模型账单时会收到一个让你怀疑人生的数字。提前分步记录哪一步贵、哪一步便宜一目了然。2.4 反思的触发时机不是每一步都要回头想前面提到反思很重要但这不意味着每一步都要触发一次全面的反思。原因很简单反思本身是有成本的它会多消耗一轮推理token而且过高频率的反思会让Agent变得犹豫不决本来执行得好好的非要停下来想想“我的目标是什么”反而拖慢节奏。我常用的反思触发条件有四个。第一个是“行动失败”比如工具返回status为error这时候必须让模型停下来判断是重试、换工具还是放弃。第二个是“结果与预期不符”比如模型要的数据是数值类型但工具返回了空列表说明哪里不对。第三个是“子任务完成”比如配置已经应用完毕模型需要判断整个大任务是否就此收尾。第四个是“达到最大循环阈值”比如已经循环了N轮还没搞定需要强制让模型总结一下当前状态防止它无头苍蝇一样乱转。反思环节也需要一个提示词模板来约束输出否则模型可能写一大段感想反而耽误时间。我用的反思提示词是这样的请根据以下信息判断当前任务状态 - 目标{task_goal} - 当前轮次{step} - 最近一次观察结果{observation} - 历史行动摘要{action_history} 请输出以下JSON格式的判断结果 {continue: true/false, reason: 简短原因, next_plan: 下一步计划或调整方案}有了这个结构化约束模型的反思会变得非常干脆。比如它可能输出“continue: true, reason: 已获取到IP地址下一步需要登录主机执行配置检查, next_plan: 调用get_host_info工具”这比一堆长篇大论可操作性强太多。3. 实操演示让一个循环在真实任务中完整跑起来3.1 场景设定与工具集准备理论说完了上一段真实的代码。我这里用一个简化的模拟场景来演示假设我们有一个“某跨平台系统配置比对与修复模拟Demo”任务是根据目标配置标准检查一批主机发现不一致的就把配置修好。工具集设计成五个get_host_list: 获取所有待检查的主机ID列表。get_host_info: 获取一台主机的当前配置信息。get_desired_config: 获取某服务的目标配置标准。apply_config: 向一台主机应用新配置。verify_config: 验证一台主机是否符合目标配置标准返回完整的差异项。这个工具集是模拟的但结构跟真实业务几乎没有区别。关键是每个工具的输入输出都要明确模型才能正确调用。工具注册代码大致长这样tools { get_host_list: { description: 获取所有待检查的主机ID列表返回一个包含host_id字段的数组。, parameters: {} }, get_host_info: { description: 获取指定主机的当前配置信息包括操作系统版本、CPU核数、内存大小、磁盘分区。, parameters: {host_id: {type: string, required: True}} }, get_desired_config: { description: 获取指定服务的目标配置标准返回一个包含所有必需配置项的字典。, parameters: {service_name: {type: string, required: True}} }, apply_config: { description: 将一份配置字典应用到指定主机返回应用结果。, parameters: { host_id: {type: string, required: True}, config: {type: object, required: True} } }, verify_config: { description: 验证指定主机是否符合目标配置标准返回差异项列表。, parameters: {host_id: {type: string, required: True}} } }工具描述直接用一句话说清楚“这个工具能返回什么、什么时候该用它”模型对工具的理解基本就靠这句话。之前我图省事写过“get_host_info: 获取主机信息”结果模型在需要获取目标配置时也去调这个工具返回的结果根本不对循环里反复绕了五六轮才自己发现。3.2 主循环的代码骨架ReAct的主循环本身并不复杂核心就是一个while循环每次迭代做三件事调用模型生成推理和动作、执行工具、把结果追加进消息列表。import json def run_react_loop(task_goal, tools, model_fn, max_steps10): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: task_goal} ] step 0 while step max_steps: step 1 response model_fn(messages) action_msg parse_json(response) thought action_msg.get(thought, ) action action_msg.get(action, ) action_input action_msg.get(action_input, {}) print(f[Step {step}] thought: {thought}) if action finish: print(f[Step {step}] 任务完成) return action_input if action not in tools: messages.append({role: assistant, content: response}) messages.append({ role: user, content: f错误工具 {action} 不存在请从工具列表中选择。 }) continue observation tools[action][func](**action_input) messages.append({role: assistant, content: response}) messages.append({ role: user, content: f观察结果{json.dumps(observation, ensure_asciiFalse)} }) return {status: failed, reason: 超过最大迭代轮次}这段代码里有一个看似不起眼但非常关键的设计当模型输出了一个不存在的工具名时我没有直接终止循环而是把错误信息作为一条观察结果塞回上下文里让模型自己纠错。这样处理比程序直接抛异常要稳得多因为模型能感知到自己错了下一轮会换一个更靠谱的动作。另一个细节是动作执行完的观察结果必须作为“user”角色的消息追加进去而不是拼在assistant消息里。这个设计是跟模型服务商的消息格式对齐的保证模型能区分“自己说过的话”和“外部环境反馈的信息”。3.3 完整循环的执行记录下面展示一段模拟执行记录可以直观感受四个环节是如何交替出现的。第一轮thought: 我需要先获取待检查的主机列表然后逐个核对配置。先调用get_host_list。 action: get_host_list action_input: {} observation: {status: success, data: {host_ids: [host-01, host-02]}}第二轮thought: 有两台主机待检查先从host-01开始。我需要获取这台主机的当前配置。 action: get_host_info action_input: {host_id: host-01} observation: {status: success, data: {os: CentOS 7.9, cpu: 4, memory_gb: 8, disk: [{mount: /, usage_pct: 80}]}}第三轮thought: host-01的根分区占用已经80%接下来我需要拿到目标配置标准看是否要求磁盘占用低于某个阈值。 action: get_desired_config action_input: {service_name: web-server} observation: {status: success, data: {disk_usage_warning_threshold: 70, memory_gb_min: 16}}第四轮thought: 目标配置要求内存至少16GB磁盘占用阈值是70%但host-01实际内存是8GB且根分区占用80%明显不达标。需要执行修复先扩容内存配置并清理磁盘。修复后必须重新验证。 action: apply_config action_input: {host_id: host-01, config: {memory_gb: 16, cleanup_disk: True}} observation: {status: success, data: 配置应用完成正在等待下一步验证}第五轮thought: 配置已应用现在验证host-01是否符合目标配置标准。 action: verify_config action_input: {host_id: host-01} observation: {status: success, data: {differences: []}}第六轮thought: 差异项为空说明host-01已经符合目标配置标准。剩余host-02还需要检查继续重复上述流程。 action: get_host_info action_input: {host_id: host-02}这个轨迹可以看到模型每一步的thought都直接指向一个明确的动作观察结果也会直接影响下一步。这就是ReAct循环的理想状态。实际运行中不会这么顺畅但设计目标就是这个方向。3.4 循环终止与结果回收循环的终止条件除了模型主动输出finish之外上线前必须加两道保险。第一道是最大迭代次数默认10轮超过直接中断并返回失败状态防止模型陷入死循环烧掉大量token。第二道是“相同动作去重”也就是说如果模型连续3轮调用同一个工具、输入几乎相同的参数说明它已经卡住了应当触发一次强制反思。结果回收也要注意。模型在最后一轮可能输出一个很长的总结文本但程序真正需要的是结构化结果。我习惯在系统提示词里约定完成任务时除输出“action: finish”之外还要让模型把最终结果放在action_input的result字段里这样程序可以直接取用不用从一大段文本里做信息抽取。{thought: 所有主机均已检查并修复完成, action: finish, action_input: {result: {checked: [host-01, host-02], fixed: [host-01], unmatched: []}}}这套约定看着简单能省掉很多后处理逻辑。写接口的人如果负责过数据清洗一定懂得从模型长文本里去捞关键信息有多痛苦。4. 常见问题与排查技巧实录4.1 模型死活不调用工具只会空谈这是初版ReAct最容易出现的问题。模型回复了一大段“我觉得应该先检查服务器状态”但就是不输出结构化动作。原因通常是提示词里没有给出足够清晰的强制格式约束或者没有给出示例。排查步骤很直接。第一检查系统提示词里是否明确写出“你必须按JSON格式输出”并在格式里列出字段。第二检查有没有给出至少一个完整的动作示例比如一轮典型的“thought action action_input”组合。第三检查返回内容是否真的不是JSON有时候模型输出的是带markdown代码块包裹的JSON解析器直接解析失败看着像“没调用工具”实际上是解析层的问题。我自己的做法是在模型输出后用一段宽松的提取逻辑先把markdown代码块剥掉再用正则找到第一个以{开头、以}结尾的子串去尝试解析。这一步防御看着Low但能救回很多本来要重试的请求。4.2 陷入死循环同一个错误反复犯死循环主要由两个原因引起。一个是模型在同一个工具报错后反复重试同一个参数因为它不知道还有别的路可走。另一个是反思环节没有真正起作用模型虽然输出了“我需要换个方式”但下一步还是选了同一个错误动作。解决思路有两层。第一层是代码层加“相同动作去重”和“连续N轮无进展自动终止”的逻辑。第二层是提示词层在反思触发时把历史行动列表直接推给模型让它核对“这些行动里有没有重复的”并明确要求它下次必须选择一条不同的路径。我在反思提示词里加了“如果连续两轮调用了相同工具且相同参数说明当前思路无效必须更换方案”这句硬约束效果很明显。4.3 工具选错模型用A工具处理B场景选错工具的根因基本都在工具描述上。描述写得太短、太宽泛、或者用的术语跟业务场景对不上模型就会选错。举个例子工具描述里写了“获取容器状态”但用户任务是“查看某服务的健康状态”模型可能不去选这个工具而去选一个名字里带“service”但功能完全无关的工具。解决办法是每个工具描述都写成“场景输入输出”三段式。比如“查询指定服务的运行状态输入服务名返回running/stopped/unknown状态及最近一次重启时间。当用户反馈某服务无法访问、需要确认服务进程是否存在时优先使用此工具。”注意第二句话写的是“什么时候该用”这一句才是模型选对工具的关键。4.4 观察结果太长把上下文窗口撑爆这是生产环境最常遇到的性能杀手。一个工具返回几万字符的日志模型还没来得及反思先因为上下文溢出开始胡说八道。处理方案是给所有工具的输出统一加一层截断和摘要逻辑。常规操作是保留前500到2000字符把包含“ERROR”“FAIL”“WARNING”关键字的行单独拎出来优先保留其余内容折叠。高级一点的思路是在工具内部就做聚合比如获取磁盘信息时工具直接把分区使用率统计成结构化数据返回而不是返回原始df输出全文。你能替模型省多少token模型就能更专注于真正的推理和决策。4.5 模型出现幻觉式观察所谓幻觉式观察是指模型没有看真实工具返回结果而是根据自己脑补写了一段“观察结果”然后顺着这个假结果继续推进。这种情况常见于模型被带偏的时候尤其是提示词里没有明确强调“观察结果只能来自工具返回内容”。我踩过的一次翻车经历模型调完工具后我在对话里追加的是“观察结果{json内容}”但中间某个转换环节不小心把观察结果和assistant自身的生成内容混在了一起模型就开始自己给自己编数据。后来我统一在提示词里写明“你只能引用上一轮观察结果里的数据严禁推测或虚构任何数值”并且代码层面严格区分助手消息和用户消息问题才根除。4.6 伪反思反思了但等于没反思最后一种问题最隐蔽模型确实输出了反思字段内容看起来也很合理但并没有影响下一步的行动选择整个反思流于形式。这种情况的本质是反思环节没有跟“下一步计划”强绑定。解决办法是把反思输出设计成一个强制包含next_plan字段的JSON格式且下一轮的thought必须引用这一轮的next_plan否则判定为无效循环。你可以在代码里做一层校验如果下一轮的thought跟上一轮next_plan完全没有语义关联就触发一次提示“你上一轮的反思中已经确定了计划请按照计划执行或说明原因”。这一招能让模型收敛快很多。下面把常见问题整理成速查表方便照着排查问题现象主要原因最直接的处理手段模型不输出动作提示词里没有格式示例补充一个完整的JSON动作示例不存在的工具名工具描述不清或模型脑补描述里明确列出所有可用工具名循环无法终止没有最大轮次限制加max_steps硬上限和超时中断同样错误反复犯反思环节与行动脱节反思强制输出next_plan并校验上下文被撑爆观察结果没有截断工具输出统一做长度限制和摘要数据是编的模型把推测当成了观察提示词强化“只能引用真实结果”解析失败模型输出带markdown或多余文本解析前剥离代码块宽松匹配JSON5. 从Demo到落地的几条工程化经验5.1 迭代上限和成本控制要提前设计ReAct的每一次循环都是一次模型调用而每次调用都要花钱、花时间。Demo里循环个五六轮没问题上了生产环境如果任务特别复杂一个用例跑几十轮费用和延迟立马失控。我的控制方法是双管齐下。第一在循环入口设一个“预算计数器”每轮调用前检查剩余预算按轮次上限和token上限两个维度卡死。第二给每个工具返回结果做量化精简控制单轮上下文增量。如果一个任务在15轮以内能完成的平均值是8轮那上限设15轮比较合理设得太大容易烧钱设得太小容易误杀正常任务。5.2 安全护栏别让Agent做它不该做的事ReAct让模型获得了调用真实工具的能力这同时带来安全边界问题。如果你的Agent能执行命令、改配置就必须在生产环境加一道硬隔离。我的经验是至少做四层防护。第一层是工具白名单只暴露任务必需的工具不要开放任何通用执行能力。第二层是参数校验工具内部对action_input做严格的格式校验和范围校验不合法直接拒绝。第三层是审批流高风险动作比如批量删除、配置变更不能直接执行先挂起等待人工审批。第四层是全程审计日志每轮行动都记录触发者、时间、动作、参数、结果一旦出事能精确定位。5.3 评估集和回归不评测就谈不上优化ReAct的调优和传统模型评测有很大区别你不能只看最终答案对不对还要看过程轨迹好不好。我的做法是维护一个几十条的评测集每条包含任务描述、期望结果、期望过程和关键陷阱。每次改动提示词或工具描述之后跑一遍全量评测集对比每个用例的完成率、平均轮次、token消耗、关键错误点。没有这个机制你很可能今天调好了A场景明天就破坏了B场景还毫无察觉。评测集里最好塞一些“故意刁难”的用例比如目标配置缺失、工具返回异常、参数名极易写错。这些边角料场景往往才是生产环境真正的翻车点。最后说一点个人体会。ReAct框架的价值不在于它有多神秘而在于它为“模型如何与外部世界交互”提供了一套极其稳定的范式。你不需要一开始就上多复杂的框架用一个while循环加一个JSON解析就能跑起来。最难的部分从来不是循环本身而是提示词协议的设计、工具的清晰定义、以及反思环节的收敛控制。这三件事做好了Agent的可靠性会有一个质的提升。我自己调完这几轮之后最大的感受是别急着把循环调得太“聪明”先让每一步都稳定、可控、可回溯智能最后会自己长出来。