企业官网建设流程全解析

先说我自己的判断：ReAct 这个框架，在 Agent 领域里不是最性感的，但很可能是最能帮你真正把 Agent 用起来的那个。原因很简单，它足够简单，简单到你可以在一晚上读懂它的论文、看完核心代码、甚至直接改出一个属于自己的智能体。而恰恰是这种“简单”，让它在未来一两年内会成为大多数通用任务自主智能体的底层范式。

网上聊 Agent 的文章很多，但大多是概念层面的“空中楼阁”。这篇东西不一样，我会从一个实际构建者的角度，把 ReAct 框架从论文思想拆到代码实现，再带你走一遍完整的手写 Agent 构建过程。全程不绕弯子，不堆术语，该写代码的地方直接写，该解释原理的地方用大白话给你说透。读完之后，你可以直接对着这份内容把代码跑起来，然后在这个基础上去扩展你自己的工具集和场景。

1. 为什么现在是 Agent 的爆发前夜，以及 ReAct 扮演的角色

先说清楚一个背景：为什么这个时间点谈通用任务自主智能体是真正有意义的，而不是又一轮技术炒作。

1.1 Agent 生态的“工具时代”刚刚到来

过去两年，大语言模型的能力大家有目共睹，但绝大多数应用还停留在“单轮问答”或“多轮聊天”的层面。简单说，模型再聪明，它也只能“想”，不能“做”。你问它明天的天气，它能告诉你天气预报的原理，但如果你不接天气 API，它永远说不出“明天下午会下雨”。

打破这个天花板的钥匙就是 Agent——让模型不只是一个回答问题的机器，而是一个能调用外部工具、观察结果、继续推理、直到完成任务的执行者。而 Agent 能爆发，底层依赖的是几件事同时成熟了：

• 模型本身的理解能力和指令遵循能力大幅提升，能够理解“你要调用工具”这件事。
• 工具生态爆炸式增长：搜索、代码执行、数据库查询、各类业务 API，甚至可以通过一些平台快速封装自己的工具。
• 框架层逐渐统一，而 ReAct 正是被吸收进主流框架的核心范式之一。

1.2 ReAct 到底是什么，它解决了什么问题

ReAct 的全称是Reason + Act，也就是“推理与行动协同”。它在 2022 年底被提出来，思路直接得有点不像学术界的东西：

让模型在每一步输出的时候，同时生成推理过程和行动指令，然后根据行动的结果再继续推理。

这个想法用大白话讲，就是“想一步，做一步，看结果，再想下一步”。看起来天真，但它精准地解决了大模型最让人头疼的几个问题：

• 答案幻觉问题：模型直接回答问题时，经常一本正经地胡说八道。但如果它先去查资料、再基于查询结果回答，信息来源就变得可靠了。
• 多步复杂任务断裂问题：让模型一次性回答一个复杂问题，它经常漏掉步骤。但让它一步一步“观察-行动-再观察”，相当于把任务拆解并强制按顺序执行。
• 逻辑可追踪问题：以前的模型回答是一个“黑盒”，你不知道它为什么这么答。ReAct 把推理过程写到明面上，每一步干了什么、查了什么、推导出什么结论，清清楚楚。

说句实在话，ReAct 并不是什么“改变世界的复杂系统”，它更像是给了模型一个极其聪明的“行为准则”。但就像一个简单的流程规范能把混乱的团队盘活一样，这个框架把大模型从“嘴强王者”变成了“动手干将”。

2. 拆解 ReAct 的三大核心机制：Thought 行动、Action 操作、Observation 观察

要把 ReAct 真正用到自己的项目里，光知道“想一步做一步”是不够的。你要理解它每一步在设计层面的讲究，以及为什么顺序不能乱。

2.1 Thought 行动：模型如何规划下一步

在每一轮迭代里，模型首先要输出一段“思考过程”，也就是 Thought。这个思考过程不是什么玄学，它的本质是让模型在行动前先暴露自己的推理意图。

举一个实际例子。假设用户问：“北京今天适合穿短袖吗？”

• 如果模型直接回答，它只能凭训练数据猜。
• 但在 ReAct 框架下，它会先输出一个 Thought：“我需要先获取北京今天的天气信息，包括气温、风力、天气状况，才能判断适合穿什么。”

不要小看这一步。让模型显式地写出思考内容，相当于强迫它在动手之前先做一次“内部规划”。这在复杂任务里尤其重要——你写了思考过程，模型就更容易发现自己“下一步到底该做什么”，很少会出现毫无逻辑地乱调工具的情况。

实操层面的建议是：在 Prompt 里描述 Thought 的格式时，务必明确要求“必须用自然语言描述当前推理过程和下一步意图”，不要让它只输出一个 JSON 动作，否则很容易退化成“瞎调工具”。在我实际项目里，绝大部分逻辑混乱的 Agent，问题都出在 Thought 输出的引导词写得太弱。

2.2 Action 操作：工具调用的规范和结构化协议

有了想法，就要动手。Action 就是模型向外部世界发出的“指令”。在 ReAct 原始论文里，Action 是用一段文本描述的，例如：

Action: Search[北京 天气]

而在实际工程实现中，我们通常把它结构化成更严格的格式，方便代码解析。我用的最多的格式是这样：

{ "action": "get_weather", "action_input": { "city": "北京", "date": "今天" } }

这一步最关键的工程问题，是格式的稳定性和可解析性。模型输出的文本是自由的，但你的代码必须能从自由文本里稳定地提取出“工具名”和“参数”。所以我强烈建议你在 Prompt 里明确要求模型用严格的 JSON 格式输出动作指令，并且给出“错误示例”。

你必须严格按以下JSON格式输出你的动作指令： {"action": "工具名", "action_input": {"参数名": "参数值"}} 注意：不要输出任何与JSON无关的内容，不要用markdown代码块包裹，不要输出解释文字。

这里有个我踩过的大坑：如果不做严格要求，模型经常会把动作指令写在 JSON 外面，或者把自然语言和 JSON 混在一起。你的解析代码就会变成“猜谜大赛”，这在生产环境里是绝对不可接受的。

2.3 Observation 观察：外部世界反馈如何回流到模型

模型执行了 Action 之后，外部工具会返回一个结果，这就是 Observation。这个结果会成为下一轮 Thought 的输入，从而形成一个闭环。

举例来说，上一步模型调用了“获取北京天气”，工具返回了：

{ "temperature": 31, "condition": "晴", "humidity": 40, "wind_level": 2 }

这个 Observation 会被拼接到模型的历史消息里，模型看到这个结果后，会继续输出下一轮 Thought：“北京温度31度，天气晴，湿度较低，风力2级，适合穿短袖，但要注意防晒。”然后它就可以直接生成最终答案了，不需要再调用工具。

这里重要的经验是：Observation 的质量直接决定了 Agent 的上限。如果你的工具返回的是凌乱的、缺字段的数据，再聪明的模型也推理不出准确结论。所以，你自己写的工具函数，除了完成业务逻辑之外，一定要专门做“结果清洗和结构化”。我习惯让所有工具都返回标准 JSON，并在函数 docstring 里写清楚“返回字段的含义”，这样能大幅提升模型的后续推理准确率。

2.4 循环：一句话概括整个 Agent 的执行流程

把三个核心机制串起来，一个通用 ReAct Agent 执行流程就是：

输入用户问题 → 循环执行: 生成Thought → 生成Action → 执行工具 → 得到Observation → 回到生成Thought → 直到模型认为任务完成 → 输出最终答案

我实际写代码时，会把“循环终止条件”设计得很明确：要么模型输出了 Final Answer 标记，要么循环次数达到了预设上限（比如 10 次）。这两个条件缺一不可，否则你的 Agent 会为了一个小问题跑上一整天。

3. 完整实操构建：从零手写一个通用任务自主智能体

前面把原理拆透了，现在进入最实在的部分：手把手构建一个 ReAct Agent。我会用 Python 语言，不依赖任何重量级框架，让你能直观看到 ReAct 每一行核心逻辑的实现。你可以把它看作一个“最小可用原型”，生产环境的扩展边界我会在第 5 节里讲。

3.1 环境准备和基础依赖安装

在开始之前，你需要准备一个 Python 3.9 以上的环境，以及一个大模型 API 的访问权限。我这里的示例用的是 OpenAI 接口风格，但逻辑同样适用于其他兼容接口的模型。如果你用的是本地模型，只要接口格式类似，也能跑通。

# 建议在虚拟环境中安装 pip install openai python-dotenv

安装完成后，在项目根目录创建.env文件，写入你的 API Key 和模型配置。

LLM_API_KEY=你的key LLM_BASE_URL=https://你的api地址 LLM_MODEL_NAME=你的模型名

这里我故意不写死某个厂商，因为不同的开发场景会用到不同的模型。你在做原型验证时，可以用任意你手头有的模型，我的切身体会是：只要指令遵循能力不差的模型，跑通 ReAct 问题都不大；真正拉开差距的，是工具定义和 Prompt 质量。建议先在自己熟悉的模型上跑通，再迁移到生产环境更合适的模型。

3.2 工具函数设计：先定义 Agent 能做什么

ReAct 的核心灵魂是 Tool（工具）。Agent 的能力边界，完全取决于你给它接了什么工具。我先写两个最简单、最容易验证的工具：一个是“获取城市天气”，一个是“计算器”。

我把每个工具函数故意写得“有业务逻辑、有规律”，而不是单纯的 API 转发。因为工具返回的 Observation 质量，是 Agent 推理准确度的基础。所有工具函数我们统一加上一个_run()方法，这样后面写代码循环时调用起来非常干净。

# tools.py import json import math import random class BaseTool: """所有工具的基础类""" name = "base_tool" description = "" def _run(self, **kwargs): raise NotImplementedError def run(self, **kwargs): try: result = self._run(**kwargs) # 统一封装成结构化的JSON返回 return { "success": True, "tool": self.name, "result": result } except Exception as e: return { "success": False, "tool": self.name, "error": str(e) }

然后定义两个具体工具。

class GetWeatherTool(BaseTool): name = "get_weather" description = "获取指定城市当天的天气情况，包含温度、天气现象、湿度和风力等级等信息。输入参数：city（城市名）。" def _run(self, **kwargs): city = kwargs.get("city", "") # 本地演示用mock数据，实际项目中你完全可以替换成真实天气API mock_data = { "city": city, "temperature": random.randint(28, 35), "condition": "晴" if random.random() > 0.3 else "多云", "humidity": random.randint(30, 70), "wind_level": random.randint(1, 4) } return mock_data class CalculatorTool(BaseTool): name = "calculator" description = "进行数学计算，支持四则运算、乘方、三角函数等，输入参数：expression（数学表达式字符串）。" def _run(self, **kwargs): expression = kwargs.get("expression", "") # 安全校验：只允许包含基本的数学字符 allowed_chars = set("0123456789+-*/()., %") for ch in expression: if ch not in allowed_chars and not ch.isalpha(): if ch not in ["s", "i", "n", "c", "o", "t", "p", "q", "r", "x", "a", "b", "l", "g", "e", "f", "m", "d", "u"]: raise ValueError(f"非法字符: {ch}") # 因为演示所以不做更多防护，生产环境要用eval的安全替代方案 result = eval(expression, {"__builtins__": {}}, {"math": math}) return {"result": result}

有关CalculatorTool，我想多说一句。生产环境下用eval实际上是危险的，你在自己项目里必须严格限制输入，或者用一种安全的表达式解析器才行。这里只是为了让大家看明白 ReAct 的流程，所以演示性质比较强，千万不要直接照搬到线上。一个更安全的做法是限制字符，或直接使用像asteval一类的安全解析库。

定义工具之后，做一个简单的工具注册表，方便 Agent 根据名字找到对应的执行函数。

TOOL_REGISTRY = { tool.name: tool for tool in [GetWeatherTool(), CalculatorTool()] } def execute_tool(name, params): tool = TOOL_REGISTRY.get(name) if not tool: return {"success": False, "error": f"未找到工具: {name}"} return tool.run(**params)

3.3 核心 Agent 逻辑：循环、消息历史与终止条件

Agent 类的核心逻辑并不复杂，最重要的就是维护“消息历史”，也就是把系统提示、用户问题、每一步的 Thought/Action/Observation 都按顺序放入消息列表，然后反复让模型基于完整历史生成下一步。

需要先说明一点：不同模型的接口格式可能有差异，我这里用的是最通用的 chat 补全格式。你要做的是把消息列表传给你的模型接口，把返回内容解析出来。下面是具体代码。

# agent.py import json import os from openai import OpenAI class ReActAgent: def __init__(self, llm_client, model_name, tools, max_iterations=8): self.llm_client = llm_client self.model_name = model_name self.tools = tools self.max_iterations = max_iterations self.messages = [] self._build_system_prompt() def _build_system_prompt(self): """构造 ReAct 的系统提示词，关键中的关键""" tool_descriptions = [] for tool in self.tools: tool_descriptions.append( f"工具名称: {tool.name}\n工具描述: {tool.description}" ) tool_desc_text = "\n\n".join(tool_descriptions) system_prompt = f""" 你是一个通过反复思考、调用工具、观察结果来完成任务的智能体。 你有以下工具可用： {tool_desc_text} 请严格遵循以下工作流程： 1. 每次行动前，先输出你的Thought（思考过程），用自然语言描述你打算做什么、为什么要这样做。 2. 然后输出Action（动作指令），必须严格使用如下的JSON格式，不允许添加任何其他内容： {{"action": "工具名", "action_input": {{"参数1": "值1", "参数2": "值2"}}}} 3. 当工具返回结果后，你会看到Observation（观察结果），基于该结果继续思考。 4. 当你认为任务已经完成时，输出Final Answer（最终答案），格式为： Final Answer: 你的最终回答 注意： - 如果任务需要多步才能完成，你必须一步一步来，每一步只调用一个工具。 - 工具可能返回错误信息，请根据错误信息调整你的行动方案，不要重复同样的错误。 - 最终答案必须基于工具观察到的真实数据，不要臆造。 """ self.messages.append({"role": "system", "content": system_prompt}) def run(self, user_query): """执行完整流程""" self.messages.append({"role": "user", "content": user_query}) for i in range(self.max_iterations): print(f"\n===== 第 {i + 1} 轮 =====") # 调用模型推理 response = self.llm_client.chat.completions.create( model=self.model_name, messages=self.messages, temperature=0.2, ) assistant_text = response.choices[0].message.content.strip() print(f"模型输出:\n{assistant_text}\n") # 检查是否结束 if "Final Answer:" in assistant_text: final_answer = assistant_text.split("Final Answer:")[1].strip() print(f"任务完成，最终答案: {final_answer}") return final_answer # 尝试从模型输出中解析Action action = self._parse_action(assistant_text) if action is None: # 如果解析失败，要求模型重新输出正确格式 self.messages.append({"role": "assistant", "content": assistant_text}) self.messages.append({ "role": "user", "content": "你输出的Action格式无法被解析。请重新输出，必须严格使用{\"action\": \"工具名\", \"action_input\": {...}}的格式，不要添加其他内容。" }) continue # 执行工具 tool_name = action.get("action") tool_input = action.get("action_input", {}) observation = self._execute_tool(tool_name, tool_input) # 将本轮完整信息追加到消息历史中 self.messages.append({"role": "assistant", "content": assistant_text}) self.messages.append({ "role": "user", "content": f"Observation: {json.dumps(observation, ensure_ascii=False)}" }) print("达到最大迭代次数，强制停止。") return "任务未在限定步骤内完成。" def _parse_action(self, text): """从模型输出中解析Action""" try: # 优先尝试直接从全文解析JSON start = text.find("{") end = text.rfind("}") if start != -1 and end != -1: json_str = text[start:end + 1] return json.loads(json_str) except Exception as e: print(f"JSON解析失败: {e}") return None def _execute_tool(self, tool_name, tool_input): """根据工具名和参数执行工具""" from tools import execute_tool print(f"执行工具: {tool_name}, 参数: {tool_input}") result = execute_tool(tool_name, tool_input) print(f"工具返回: {json.dumps(result, ensure_ascii=False)}") return result

用一句话概括这个 Agent 类的逻辑：一个带终止保护的 while 循环。终止条件有两个，一个是模型主动给出 Final Answer，另一个是达到max_iterations上限。

3.4 运行演示：完整输出 Agent 的思考轨迹

万事俱备，现在写一个入口文件跑一次完整流程，看看输出效果。

# main.py import os from dotenv import load_dotenv from openai import OpenAI from agent import ReActAgent from tools import GetWeatherTool, CalculatorTool load_dotenv() client = OpenAI( api_key=os.getenv("LLM_API_KEY"), base_url=os.getenv("LLM_BASE_URL"), ) agent = ReActAgent( llm_client=client, model_name=os.getenv("LLM_MODEL_NAME"), tools=[GetWeatherTool(), CalculatorTool()], max_iterations=8, ) result = agent.run("北京今天天气怎么样？如果温度超过28度，请告诉我明天可能需要涂防晒霜吗？") print(f"\n最终结果: {result}")

我用一个简单的问题串起了两个工具：“天气查询”和“判断温度”。这个任务刚好能展示 ReAct 的多步推理能力。真实运行输出大概是这样：

===== 第 1 轮 ===== 模型输出: Thought: 我需要获取北京今天的天气信息，才能判断是否需要涂防晒霜。 Action: {"action": "get_weather", "action_input": {"city": "北京"}} 执行工具: get_weather, 参数: {'city': '北京'} 工具返回: {"success": true, "tool": "get_weather", "result": {"city": "北京", "temperature": 32, "condition": "晴", "humidity": 40, "wind_level": 2}} ===== 第 2 轮 ===== 模型输出: Thought: 北京今天温度32度，天气晴，湿度40。由于温度超过28度，紫外线照射较强，建议涂防晒霜。 Final Answer: 北京今天32度，天气晴朗，体感较热。由于温度超过28度，明天白天紫外线仍然较强，建议涂防晒霜，同时注意补水和防晒。

从这个输出里你可以直观看到，模型第一步做了“决策”，第二步做了“结论”，并且每一步都有依据。这里的运行结果完全符合预期，同时也展示了 ReAct 最迷人的地方：每一步推理和决策都是透明的、可审计的。

4. 实际构建中的高频问题与排查锦囊

我写了不少 Agent 了，这个环节是干货中的干货。ReAct 用起来确实不难，但在实际项目里，你会发现很多论文里永远不会告诉你的问题。我把它们整理成了一份问题速查表，每个问题都附上我实战总结的解决思路。

4.1 循环卡死问题：一个必须自带的保险丝

循环卡死，就是我之前说的“Agent 进入死循环”。比如模型反复查询同一天气，或者反复调用同一个失败的工具。我见过有同学在演示时没加迭代上限，结果一个简单任务跑了十分钟还在循环。

这个问题，解决思路分两层：

第一层，硬性保护：必须有max_iterations。无论你的 Prompt 写得多好，都要给循环加上保险丝。我习惯是简单任务用8步上限，复杂任务用20步上限，并且超过上限后要让 Agent 返回“当前已完成部分+未完成原因”。

第二层，软性纠偏：你在 Prompt 里明确告诉模型，Observation 如果返回 error，要理解错误原因并更换策略。模型很擅长解决“它自己造成的错误”，前提是你给了它足够的信息。

4.2 Observation 文本过长/内容无用的情况

这种情况太常见了：工具返回了一堆原始数据，比如一个搜索 API 返回了 100 条结果，但模型真正需要的信息只有前三条。

我有两个亲测有效的处理方案：

第一个方案：在工具函数内部做“结果精简”。搜索工具不要直接返回原始结果列表，而是只返回标题加摘要，甚至你可以再加一层“结果摘要”预处理，用一个较小的模型对 100 条结果做一次浓缩。

第二个方案：在工具描述里写清楚“返回信息的字段含义”，并用一个简短的示例说明如何使用这些字段。这个方法能显著提升模型对 Observation 的利用率，因为模型不再需要猜测字段含义。

4.3 模型的“工具调用记录”和“用户输入”混淆问题

在某些情况下，模型可能会错误地认为 Observation 是“用户说的话”，导致它开始跟用户对话，而不是继续推理。

解决办法是在系统 Prompt 中明确区分各种角色的措辞：

- 如果你是收到 Observation，代表的是工具执行结果，你应该基于结果继续任务。 - 用户的消息只会在任务的初始阶段出现一次，后续你收到的所有非工具执行结果的消息都被视为 Observation。

这个看起来有点傻，但它确实能有效防止模型进入“对话模式”而忘了自己的 Agent 身份。

5. 从 Demo 到可用：三个关键方向优化方案

写完一个 Demo Agent 不难，难的是让它真正可以用于实际工作。基于我在多个项目中的经验，有三个方向是最值得升级的。这里涉及很多工程取舍，我把思路和部分实现都写出来。

5.1 从单工具到多工具组合

一个生产级 Agent 往往需要几十个甚至上百个工具。这时你的挑战就不再是“写一个工具”，而是“让 Agent 知道在什么场景下选哪个工具”。

我推荐的做法是给每个工具名加上“场景前缀”，同时在工具描述里写清楚“这个工具适合用来做什么、不适合用来做什么”。举个例子：

工具名称: user_data_query 描述: 查询用户基础信息，包括注册时间、会员等级、手机号等。适用于需要用户纬度信息的任务。不适合查询订单明细（请使用order_query）。

这样模型在选择工具时会更加准确，不会被相似名称搞混淆。我这里心得是：工具描述写得越具体，大模型选错工具的概率越小。

5.2 从单步工具调用到多 Agent 协作

当单一 Agent 的处理能力不够时，你可能需要拆成多个角色 Agent，比如“规划 Agent”负责拆解任务，“执行 Agent”负责调用工具，“审查 Agent”负责验证结果。这时 ReAct 就不再是单个 Agent 的内部流程，而是变成了多个 Agent 之间的协作协议。

这种设计适合比较重的任务场景。我建议你在真正觉得“单个 Agent 已经无法解决问题”的时候再去引入多 Agent。否则只会增加系统的复杂度和容错难度。

5.3 引入记忆和上下文压缩

ReAct 本身没有记忆机制，它的记忆完全依赖于每一轮的上下文历史。一旦历史过长，就会达到模型的上下文窗口上限。生产环境常用的方案是：

• 滑动窗口：只保留最近 N 轮的消息。
• 摘要记忆：每隔几轮，用模型把历史归纳成一段摘要，把摘要保持在上下文中。
• 向量检索记忆：把重要的历史信息存储下来，需要时按相关性取回。

这三种方案的复杂度从上到下递增，但效果也是递增的。原型阶段用滑动窗口就足够了，核心目的是“别让程序报错”；生产阶段建议至少接入摘要记忆，否则很难处理长任务。

6. 一点心得：ReAct 并不是万能银弹

把整套流程走下来之后，我想说几句掏心窝的话。

ReAct 框架给了我一个很好的起点，但它本质上是“给了模型一个行为准则”，这个准则能否真正发挥价值，取决于三个外部因素：模型能力、工具质量、任务边界。模型太弱，再好的准则也白搭；工具返回一堆垃圾，再聪明的模型也推理不出有价值结论；任务边界模糊，Agent 就会在探索的路上一去不回。

我在实际做项目的过程中，最后得出的铁律是：不要把 Agent 当成万能机器人，要把它当成一个配合默契的新员工。你需要告诉它公司的规矩（系统 Prompt）、提供趁手的工具（Tool 设计）、设定清晰的目标和边界（任务定义与终止条件），然后给它一定的试错空间（循环机制）。这样它才能真正像一个可靠伙伴一样干活。

如果你正准备开始自己的 Agent 项目，我建议你从今天这套代码改起，加上你自己的一个工具类，跑一个真实的小任务，先感受一下整个推理闭环的乐趣。当你看到模型真的“思考-调用-反馈-总结”地完成一个任务时，你会重新理解大模型的能力边界。之后再去接触更复杂的 Agent 系统，你会发现自己已经具备了最核心的判断力。