ReAct模式从原理到实战：构建高效LLM Agent的完整指南-北京尧图网络

做LLM应用开发的同行最近应该都被Agent这个词刷屏了。翻开源代码无论是成熟框架还是个人Demo大部分都绕不开ReAct模式。我最初接触ReAct时以为是什么高深莫测的新架构真正啃完论文、动手写过几轮之后才发现它的核心思想朴素得惊人让模型一边“思考”一边“行动”把外部工具的回执当成继续推理的燃料。这篇东西我整理了ReAct从理论到落地的一套完整笔记包含我实际开发中踩过的坑和调优思路花了不少时间希望能帮到正在做Agent开发或者准备入坑的朋友。1. ReAct模式核心思路拆解ReAct这个名字是Reasoning和Acting的拼接直译过来就是“推理行动”。最初读论文的时候我以为作者搞了什么复杂的数学框架后来发现本质是提示词工程和决策循环的结合它解决的问题非常实际大模型单独靠内部知识推理容易在复杂任务上胡思乱想单独靠外部工具调用又缺乏长远规划。ReAct把这两种能力拧成一股绳让模型在每一步都先想清楚“现在该做什么”再动手去执行。1.1 ReAct要解决的本质问题先看传统做法的问题在哪。以前做任务型对话或简单机器人最常见的方案是“意图识别槽位填充”本质是给模型一个固定的工作流让它按预设路线走。这套路在面对固定场景时很稳但一旦遇到开放式任务比如“帮我调研一下某行业的近期动态并生成报告”系统就抓瞎了意图不明确槽位无法预定义工作流根本没法枚举。这是第一个痛点固定流程撑不住开放式任务。另一个痛点是纯推理模式的局限。很早就有人尝试让大模型直接“想”出答案也就是思维链Chain of Thought。思维链在数学题和逻辑题上效果拔群但碰到需要实时信息的场景就露馅了——你让模型推理今天天气它只能靠训练数据里的先验知识瞎猜。这是第二个痛点纯推理拿不到实时信息也无法验证自己的猜测。ReAct的厉害之处在于把“推理”和“行动”循环起来了。模型每输出一步推理就根据推理结果发起一次工具调用拿到真实回执后再把新信息塞回上下文继续推理。整个过程像人做事的方式先想一想当前状况查点资料再基于新信息想下一步。这种循环天然适配开放式任务因为模型每一步都在依据最新事实重新规划而不是死板地走预设流程。这里的关键词是“循环”。ReAct不是一次性的提示词而是一个持续迭代的过程。每一步循环里模型输出的文本被拆成两部分一部分是Thought思考另一部分是Action行动。系统截获Action执行对应的工具再把Observation观察结果返回给模型。模型看到Observation后再生成新的Thought和Action直到它认为任务完成输出Final Answer。整个循环跑下来模型是在“动脑”和“动手”交替中进行这比单纯推理或单纯执行都更接近真实世界的任务解决方式。1.2 与工具调用范式的关键区别很多朋友会把ReAct和普通的功能调用Function Calling搞混。两者都能让模型调用外部工具但底层的逻辑完全不同。用大白话解释Function Calling像点菜你把菜单递过去模型选一个菜厨师做好端上来ReAct更像让模型自己当主厨它不光要选菜还要自己设计烹饪步骤尝一口味道不对还得自己调整方案。这种区别在实现层面非常明显。Function Calling通常是由系统预先定义好一系列工具模型在生成回复时附带一个结构化调用指令系统执行后把结果拼回去。整个流程往往是单轮的模型调一次工具就生成最终回复。ReAct则是多轮的决策循环模型在每一轮都可以选择继续思考、调用工具或者终止任务给出最终答案。系统不会假设模型调用一次工具就能完成任务而是持续地把每一步的反馈送回上下文直到模型自己认为可以收尾。再往深处说ReAct对模型的输出格式有更强的约束。它要求模型在输出中显式地标记Thought、Action、Action Input这些字段系统用解析器把Action字段提取出来执行。相比之下Function Calling通常用更结构化的JSON Schema来约束输出。ReAct这种文本标记的方式更灵活能适配更多场景但对模型遵循指令的能力要求也更高。实际测试下来如果模型指令跟随能力弱写出来的Action字段经常解析失败后面我会专门讲这个问题怎么处理。理解了这个区别你就能明白为什么Agent框架如某些流行的开源Agent框架都在用ReAct模式它足够通用不局限于预先定义的工作流能处理开放式的多步任务。这也是ReAct被称为Agent开发基石的原因。2. 从零构建ReAct智能体架构设计与工具选型理论说完直接进入动手环节。构建一个ReAct智能体核心就三件事设计提示词模板、实现工具调用回路、管理多轮上下文状态。这三个模块配合好了一个能跑通的Agent就到手了。我这里从架构层面讲清楚每个模块的职责和设计思路再给出可直接复现的代码框架帮助你快速搭起自己的ReAct智能体。2.1 核心模块拆解ReAct智能体的架构可以拆成五个核心组件每个组件都有明确的职责边界理解了这点后续扩展和维护都会很轻松。这五个组件分别是提示词模板、解析器、工具注册表、执行器、上下文管理器。提示词模板是整个Agent的“大脑说明书”它告诉模型三件事你是做什么的、你能用哪些工具、你该怎么思考和输出。模板质量直接决定了模型的表现这里最容易踩的坑是把模板写得过复杂。我见过有人把一个Agent的提示词写到几千字结果模型在各种约束里绕晕了输出五花八门。好的模板应该简洁明确重点突出工具清单和输出格式角色设定一带而过就够。解析器负责把模型输出拆解成结构化指令。模型输出通常是一段文本里面混着Thought、Action、Action Input等字段。解析器要做的事情就是从这段文本里提取出Action和Action Input交给执行器去调用工具。解析看起来简单实际坑最多。模型经常不按格式输出我遇到过Action字段写了但Action Input里夹带私货或者把Thought写成了Action Input的一部分。解析器的设计要尽量容错但容错不是无限的后面我会分享一套多级解析策略。工具注册表是所有可用工具的目录它维护工具名称与真实代码的映射关系。每个工具在注册表里有一个唯一的名称一段描述解释工具能做什么、什么时候用以及输入参数定义。这部分的爆炸点在于工具描述的质量描述得好模型就知道工具是干嘛的、什么时候该调描述得模糊模型就把工具晒在一边不调用或者把参数传错。执行器是真正的“动手”模块。它收到解析器提取的Action和Action Input后在注册表里找到对应函数把参数填进去执行代码拿回一个字符串结果这个结果就是Observation。执行器本身不复杂但要注意异常处理。工具执行会抛错甚至可能因为输入参数不对而崩溃执行器必须把异常捕获并转成可读的文本返回给模型让模型知道发生了什么而不是直接让整个流程崩溃。上下文管理器维护对话的历史记录。ReAct循环中每一步产生的Thought、Action、Observation都要追加到上下文里。这里的关键决策是上下文窗口管理。大模型有最大输入长度限制循环多了上下文很容易爆掉。上下文管理器需要做好截断、摘要、或者关键信息提取保证循环能持续跑下去同时不丢失核心信息。2.2 工具选型与上下文管理策略有了架构认知接下来看工具选型。做ReAct智能体工具是你给模型配置的“双手”质量比数量重要得多。很多新手一上来就给Agent塞十几个工具恨不得把什么功能都包装成工具结果模型反而不会用原因很简单工具一多选择就困难了模型在犹豫之间随便挑一个或者根本不调用。我的建议是工具宁缺毋滥。先把最核心的几个工具写上比如搜索引擎、计算器、数据库查询跑通了再逐步增加。每一个工具的描述必须写得精准清晰说清楚“这个工具是干嘛的”“什么场景下适用”。描述写得好的标准是模型读完不用思考就能判断该不该用。描述写得差的典型症状是工具列表里明明有合适的功能模型偏不用硬靠自己的训练数据瞎编答案。工具选型还有个容易被忽视的维度工具返回结果的数据格式。理论上ReAct的Observation只是给模型“看”的文本但格式太乱会让模型抓狂。比如你调用一个搜索工具返回的是JSON里嵌着一堆嵌套字段模型可能要反复猜测哪个字段才是它需要的。工具设计上能做的是把返回结果尽量规范化比如搜索结果就输出一个纯文本的标题摘要列表数据库查询就输出格式规范的表格文本。Observation干净了后续推理的准确率会明显提升。上下文管理策略我直接说实践结论。最好的方案是维护一个滑动窗口只保留最近的若干轮Thought和Observation。窗口大小取决于模型的上下文能力常见的大小在10到20轮之间。超出窗口的旧内容不能直接丢弃因为可能会有关键信息在里面。我的习惯是做一个摘要线程每超过窗口就触发一次摘要把旧信息浓缩成几句话放回上下文。这样模型既能保留长期记忆又不会因为上下文爆炸而分心。还有一个重要策略叫“早停”。不是所有任务都需要模型跑很多轮循环有些任务一两步就完成了有些任务模型明显在无效循环里打转。上下文管理器需要记录一个“无进展轮数”如果连续几轮Thought重复相似内容或者Action反复调用同一个工具拿回一样的结果就主动终止循环输出当前的最佳答案或者告诉用户任务无法完成。这个策略能显著提升用户体验也能节省Token开销。3. 实操指南手把手实现一个最小可用的ReAct智能体现在进入硬核环节。我用Python手写一个最小可用的ReAct智能体不依赖任何重型框架只靠大模型API调用和正则表达式解析。这个Demo麻雀虽小五脏俱全核心逻辑和工业级框架完全一致把代码吃透了你去看任何成熟框架的源码都会觉得似曾相识。3.1 环境准备与基础代码框架先说明一下环境要求。这个Demo需要你有一个能调用的LLM API接口以及Python 3.9的环境。我用的是OpenAI兼容接口规范你用自己的模型也完全没问题只要支持聊天补全和系统提示词就行。需要安装的依赖只有两个openai和requests前者用于模型调用后者可选用于HTTP请求。整个代码的逻辑基于一个核心循环组装消息 - 调模型 - 解析输出 - 执行工具 - 把Observation追加到消息列表 - 再调模型。直到模型输出Final Answer才停止。这个循环是ReAct的灵魂建议你先把这个骨架搭好再去填充细节。import json import re from openai import OpenAI client OpenAI(api_keyYOUR_API_KEY, base_urlYOUR_API_BASE) class ReActAgent: def __init__(self, system_prompt, tools): self.system_prompt system_prompt self.tools tools # 工具注册表格式{名称: {desc: 描述, func: 可调用函数}} self.messages [{role: system, content: system_prompt}] def call_llm(self, user_msg): self.messages.append({role: user, content: user_msg}) resp client.chat.completions.create( modelYOUR_MODEL_NAME, messagesself.messages, temperature0.3, ) content resp.choices[0].message.content self.messages.append({role: assistant, content: content}) return content def parse_action(self, text): # 简化版解析提取Action和Action Input action_match re.search(rAction\s*\d*\s*:\s*(.?)(?:\n|$), text) if not action_match: return None, None action action_match.group(1).strip() input_match re.search(rAction Input\s*\d*\s*:\s*(.), text, re.DOTALL) action_input input_match.group(1).strip() if input_match else return action, action_input def execute_tool(self, action, action_input): if action not in self.tools: return f错误未知工具 {action}请从工具列表中选择。 try: func self.tools[action][func] # 尝试解析JSON参数失败则直接当作纯字符串传入 try: args json.loads(action_input) if action_input else {} if not isinstance(args, dict): raise ValueError(参数必须是JSON对象) result func(**args) except (json.JSONDecodeError, ValueError): result func(action_input) return str(result) except Exception as e: return f工具执行出错{str(e)} def run(self, task): observation task for step in range(10): # 最大迭代10轮防止死循环 content self.call_llm(observation) print(fStep {step 1} 模型输出:\n{content}\n) if Final Answer in content: final content.split(Final Answer:)[-1].strip() print(f最终答案{final}) return final action, action_input self.parse_action(content) if action is None: # 模型没有输出Action引导它继续 observation 请继续你的推理并输出一个Action或直接给出Final Answer。 continue obs self.execute_tool(action, action_input) print(f工具反馈{obs}\n) observation fObservation: {obs} print(达到最大循环轮数停止。) return 无法在限定轮数内完成任务。这段代码的核心逻辑在run方法里。task是用户输入的任务它在第一轮被当作Observation传给模型模型看到Observation后开始推理循环。每轮循环从模型输出提取Action和Action Input执行工具后把Observation拼接成新的文本喂回模型。这里要特别提醒一个设计细节Feed给模型的Observation必须是一个明确的字符串前缀。很多模型的输出格式中包含了“Observation”这个标记你需要确保每一轮循环中模型的输入都带上了这个前缀。这是ReAct格式的约定模型依赖这个标记来区分“这是环境反馈”而不是“这是用户新指令”。初次写ReAct的人很容易在这一步犯错把Observation当成普通消息结果模型就懵了。3.2 关键实现细节解析上面的代码框架能跑但要达到实用水平还需要填充几个关键细节。首先是解析器的鲁棒性。我上面用了简单的正则但实际场景中模型生成的文本格式五花八门常见的幺蛾子有Action拼写错误、Action和Action Input写在一行、Action Input疑似多行JSON但被截断。我自己实践中用过多级解析策略。第一级用严格正则匹配“Action: xxx”和“Action Input: xxx”分别提取。如果第一级失败就用第二级宽松匹配在文本里找“Action”关键词把这一行后半部分当作动作名再往后找“Input”或“参数”把后续内容当作输入。如果两级都失败就直接把模型输出原样截取给工具当参数。多级解析不是万能的遇到彻底乱写的模型输出最合理的做法不是继续硬解析而是把解析失败的消息作为Observation反馈给模型让它自己纠正。实测下来大部分模型在收到解析失败提醒后会重新生成规范的Action。第二个细节是工具执行的异常隔离。上面代码里用了一个大try except包住整个工具调用这是必须的。工具执行可能因为各种原因失败参数缺字段、网络超时、文件不存在等等。任何未捕获的异常都会导致整个Agent崩溃这是新手最容易踩的坑。更严重的是工具返回的错误信息如果太抽象比如抛了个堆栈跟踪模型看了也看不懂。我一般会在异常捕获后把异常类型和关键信息转成一句简洁的自然语言描述比如“查询失败字段city是必填项请确认输入后重试”。这样模型才能基于错误信息自我纠正。第三个细节是最大轮数的控制。上面代码里设了10轮上限实际项目里这个值要按任务复杂度来调整。太小的值会导致复杂任务没跑完就被截断太大的值会浪费Token并可能让模型陷入无效循环。我建议初始值设为15到20然后根据日志分析每轮的实际价值和效率。如果在某类任务上Agent经常在最后几轮没有任何增量信息就该考虑缩减轮数上限减少无谓消耗。现在补上一个完整的工具注册示例好让初学者直观看到工具描述怎么写才有效def search_web(query: str) - str: 模拟一个搜索引擎工具实际项目中替换为真实API调用 results { ReAct是什么: ReAct是推理与行动的协同范式通过交替进行思考与工具调用完成复杂任务。, 大模型Agent: Agent是能够自主决策、调用工具、完成多步任务的大模型应用系统。 } return results.get(query, f关于{query}的搜索结果暂无匹配信息。) tools { search_web: { desc: 在互联网上搜索给定关键词返回相关结果的摘要。当你需要实时信息或验证事实时使用。, func: search_web } } agent ReActAgent( system_prompt你是一个智能助手可以通过调用工具来帮助用户完成任务。你有以下工具可用 - search_web: 在互联网上搜索给定关键词返回相关结果的摘要。你必须按照以下格式输出 Thought: 你的推理过程。 Action: 你要调用的工具名 Action Input: 传给工具的JSON格式参数 Observation: 由系统返回你不需要输出当你获得足够信息后输出 Final Answer: 你的最终答案, toolstools ) agent.run(请帮我查询ReAct是什么)看到这里的系统提示词你可能注意到了提示词里列出了工具清单和输出格式但没有写太多角色设定的废话。这是我在试验中总结出的实践规律。角色设定太多模型容易在创作人设上花费精力分散对工具调用的注意力。简洁的提示词让模型专注于推理和行动本身反而更容易用对工具。工具描述的清晰程度直接决定了模型能否正确选择工具这段提示词里对每个工具的描述都明确说明了用途和使用场景——这正是我反复强调的工具描述精髓。4. 常见问题与调优心得实录实战环节最不缺的就是问题。这一节我整理了自己在ReAct开发中最常遇到的几个典型问题和对应的调优策略都是常规教程不会细讲的东西。这些问题按出现的频率排序越靠前的越常见建议逐个排查。4.1 模型不按格式输出Action怎么办模型不按格式输出Action高概率出现。你明明在提示词里写了“Action: 工具名”它偏要输出“我建议你使用search_web工具”或者直接给答案。这类问题通常有两个原因模型本身指令跟随能力弱或者提示词格式说明不够强。最简单的应对策略是Few-shot示例。在系统提示词里加一个完整的示例包括Thought、Action、Action Input、Observation到Final Answer的完整链路。ReAct论文里就是用了大量示例实际测试下来Few-shot对输出格式稳定性的提升非常明显。另一个策略是后处理兜底解析不到Action时把模型的输出截断取其最后一行尝试匹配工具列表里的工具名。如果匹配到就认为模型是想用那个工具匹配不到就把整个输出当作文本返回给用户。调优建议如果以上策略都无效建议更换更强指令遵循能力的模型。ReAct对输出格式的要求比普通对话要高一个量级模型跟着能力不足时会频繁产生解析错误后续再怎么调提示词都收效甚微。4.2 观察结果太长撑爆上下文工具返回的Observation经常很长——搜索结果的摘要可能有几千字数据库查询结果可能有几百行。直接塞回上下文几轮下来窗口就满了。这个问题是所有ReAct实践者绕不开的坎。我的处理思路分三级。第一级是源头压缩在工具返回时做截断和精简比如搜索结果只保留前5条的标题和第一句摘要数据库查询结果只返回前20行并附加行数统计。第二级是上下文摘要设置一个阈值当消息历史长度超过窗口的一半时触发摘要线程把最旧的Observation压缩成一句话。第三级是自动忘记直接丢弃过旧的Observation只保留Action和对应的摘要让模型知道“之前执行过某个工具但结果细节已丢失”。工程上通常组合使用能有效延长Agent的续航能力。4.3 模型陷入重复循环浪费Token模型陷入重复循环就是它反复调用同一个工具、拿到同样的结果然后又基于同样的事实想同样的步骤。这个过程持续数轮除了消耗Token什么都没有产出。这个问题不解决Agent应用的运行成本会失控。要拦住这种空转最简单的做法是设轮数上限但更优雅的方案是加“重复检测”记录最近几轮的工具名和参数如果出发检测到相同组合出现多次就在Observation里明确提示模型“你已经查过该信息没有新增内容请换一个角度思考或直接生成最终答案”。实测下来加了这层提示后模型脱离循环的概率大大提升。另一个辅助手段是给每轮Observation加序号模型更容易察觉自己在原地打转。4.4 工具描述不清晰导致误调用这是隐性大坑Agent不是不调工具而是工具描述不到位它压根不知道该在什么时候用哪个工具。给多个工具注册表添加工具时描述写得模棱两可比如“执行系统操作”模型看了要么不敢用要么瞎调用。工具描述有一个推荐模板照着写能大幅降低误用概率工具用途一句话说清功能、适用场景列举2到3个典型使用场景、不适用场景防止模型误用、参数说明每个参数的格式和示例。模版的核心是给模型明确的“决策边界”让它能判断用还是不用。比如一个天气查询工具我会写“用于查询指定城市当天的天气情况。当用户询问城市天气时使用不要用于查询历史气候数据或全球气候变化”。这样模型的选择清晰多了。4.5 多轮交互中的状态丢失问题最后一个常见问题是状态管理。任务执行过半时用户插了一句“把刚才那个名字换成另一个”Agent可能会有困惑因为“刚才那个名字”在前面几轮出现过但已经被挤出了上下文窗口。我的应对策略是增加状态跟踪器把任务执行过程中的关键信息单独存下来比如任务目标、已确认的参数、中间结果。每轮循环开始前把状态跟踪器的内容作为观察结果的一部分注入上下文让模型始终能参考全局状态。做法有些笨重但对场景很有效。另一个轻量方案是在文本摘要时保留关键实体把用户提到的名字、数字、日期单独摘出来存到摘要线程的最前面确保在上下文压缩后还能被模型看到。5. 进阶技巧提升智能体性能的实用经验从能跑到跑得稳中间还隔着一层实践优化的功夫。这一节分享几个我在实际项目中验证过的进阶技巧它们往往能带来立竿见影的效果提升。经验一给Observation加“信息价值”标签。当工具返回结果时在Observation前加一个简短的前缀说明其价值。比如搜索结果标注“已筛选相关内容”数据库结果标注“返回5条匹配记录重点看第一条确认的客户信息”。别小看这一步它引导模型在分析时优先关注关键信息减少在海量噪声中寻找重点的时间。经验二周期性插入反思节点。在循环中每隔几轮加一个辅助提示引导模型重新审视当前的任务进度比如“你已经执行了第5轮请总结当前掌握的信息判断是否足以回答用户问题”。我实测这个技巧明显减少了过度推理。如果没有这个反思模型有时会连续调用五六轮工具最后发现绕了一个大圈。加了反思节点后模型会在适当的时机收束直接给出结论。经验三让工具返回半结构化文本。纯文本Observation虽合法但模型解析长文本的成本很高。如果Observation是一段JSON就别直接把它原样返回而是转换成人可读的半结构化文本。比如数据库查询结果转换成“字段名: 值”的列表搜索结果转换成带序号的列表。模型对这种格式的解析速度几乎快了一个数量级。经验四缓存工具结果避免重复调用。如果Agent反复查询同一个关键词把上次的结果直接返给模型节省Token和时间。这个道理跟后端接口缓存完全一致。我构建过一个简单的字典缓存key是工具名加参数value是返回结果。虽然缓存命中率不算特别高但在多轮对话里的收益仍然很可观。这些技巧看着简单但在真实项目中提升稳定性非常有效。有一次我在一个复杂调研任务里应用了反思节点和结果缓存最终Agent完成任务的轮数从平均9轮降到了6轮无效调用明显减少整体响应速度提升了一倍多。在我的实践里ReAct真正吃功夫的地方不在算法本身而在工程效率和细节。把这些问题处理好了Agent才能从“能跑”进化到“跑得稳、跑得省”。关于这个内容我踩过不少次坑后才摸索出一套相对顺手的实现路径上面记录的每个问题都是真实复盘过的。尤其是反复循环和Observation太长这两个点如果你正在开发一个长时间运行的Agent很可能会遇到建议提前做好预案。后续如果你们在实际复现中碰到什么新问题也欢迎带日志来找我讨论。

ReAct模式从原理到实战：构建高效LLM Agent的完整指南

相关推荐

8款AI文献综述工具，从检索到润色全流程指南

Agent开发实战：从API调用到智能体工作流搭建

MFC对话框背景图稳定绘制实战：绕过WM_ERASEBKGND与BitBlt陷阱

更多资讯

QtXlsx在VS2019下的编译配置与Excel读写实战

六大开源Agent框架深度拆解：任务规划、工具调用与记忆管理选型指南

安全帽佩戴检测毕设全流程：从YOLO数据准备到部署答疑

NUMA架构下PHP-FPM性能优化：从原理到绑核实操全解析

8位单片机实现模糊控制洗衣机的工程实践

SpringBoot+Vue前后端分离：小区物业管理系统源码实战解析

今日更新

电商智能运营体系从0到1：架构设计、落地步骤与避坑指南

压缩空气储能与热网热惯性联合优化调度：热电联产系统建模与求解

若依框架AI代码生成不稳定？用Agent Skill三层结构+五步法搞定

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？