Agent-study项目教程（03）：手写 Mini-ReAct Agent（不依赖框架）

一、理论部分1. Agent 的核心闭环思考 → 选工具 → 执行 → 反馈 → 再思考与“聊天机器人”不同Agent 的关键能力在于遇到需要外部信息或计算时不是直接凭空回答而是能够主动调用工具Tool完成任务并将工具结果纳入后续推理。一个最小可用的 Agent通常具备以下流程Reasoning推理判断下一步该做什么Acting行动选择一个工具并给出参数Observation观察获取工具执行结果Loop循环把观察结果反馈给模型直到得到最终答案这就是经典的ReActReason Act思路。2. 工具Tool的本质可被模型调用的函数在工程实现上工具就是一组可执行函数例如get_weather(city)查询天气本项目用模拟数据calculate(expression)计算表达式本项目用eval演示为了让模型“可选”我们通常维护一个工具注册表如tools_map实现“工具名 → 函数”的映射。模型输出工具名后程序才能准确路由到对应函数执行。3. 约束模型输出固定格式 Stop Sequence 解析要让模型稳定触发工具调用必须对输出格式做约束。本项目采用如下组合策略固定输出格式要求模型按思考/行动/行动输入/观察/最终答案的格式输出Stop Sequence调用模型时设置stop[观察:]让模型在准备输出“观察”之前停下来等待程序填入真实工具结果正则解析从模型输出中解析行动与行动输入从而驱动工具执行这三点共同解决一个问题让模型的“行动意图”可被程序可靠识别与执行。4. 结果回灌Observation 是 Agent 能多步完成任务的关键当工具返回结果后需要把结果以观察: ...的形式写回对话上下文模型才可能进行下一步推理例如先查天气再从温度提取数值再做计算。因此Observation 回灌是多步推理的必要条件。二、实战部分1. 项目目标实现一个不依赖任何 Agent 框架的 Mini-ReAct Agent支持基于固定格式的 ReAct Loop工具选择与执行天气查询、计算器多步任务能“先查再算”直到输出最终答案2. 运行准备请确保本地已安装依赖并配置环境变量依赖安装示例pipinstall-rrequirements.txt环境变量示例DEEPSEEK_API_KEYDEEPSEEK_BASE_URL说明get_weather为模拟数据仅支持少数城市如 北京/上海/Beijing/Shanghai 等calculate使用eval()仅用于教学演示不可用于生产环境3. 主要代码核心实现以下为项目核心代码包含工具定义、Prompt、循环、解析与回灌逻辑可直接运行importreimportosfromdotenvimportload_dotenvfromopenaiimportOpenAI load_dotenv()clientOpenAI(api_keyos.getenv(DEEPSEEK_API_KEY),base_urlos.getenv(DEEPSEEK_BASE_URL),)# --- 1) Tools ---defget_weather(city_name):查询天气工具。实际项目中应调用真实 API这里模拟返回。print(f [系统日志] 正在查询{city_name}的天气...)mock_data{Beijing:25°C,Shanghai:22°C,New York:15°C,北京:25°C,上海:22°C,}returnmock_data.get(city_name,未知城市无法查询天气)defcalculate(expression):计算器工具。print(f [系统日志] 正在计算:{expression})try:returnstr(eval(expression))exceptExceptionase:returnf计算错误:{str(e)}tools_map{get_weather:get_weather,calculate:calculate,}# --- 2) ReAct Prompt ---REACT_PROMPT 请尽你所能回答以下问题。你可以使用以下工具 {tool_descs} 请使用以下格式 问题: 你需要回答的输入问题 思考: 你应该总是思考接下来该做什么 行动: 你采取的行动必须是 [{tool_names}] 之一 行动输入: 行动的输入参数 观察: 行动的结果 ... (这个 思考/行动/行动输入/观察 的循环可以重复 N 次) 思考: 我现在知道最终答案了 最终答案: 针对原始问题的最终答案 开始 问题: {query} .strip()defbuild_tool_desc():desc[]forname,funcintools_map.items():desc.append(f{name}:{func.__doc__})return\n.join(desc)# --- 3) Agent Core ---classMiniReActAgent:def__init__(self,modeldeepseek-chat):self.modelmodeldefchat(self,query:str)-str:tool_descsbuild_tool_desc()tool_names, .join(tools_map.keys())promptREACT_PROMPT.format(tool_descstool_descs,tool_namestool_names,queryquery)messages[{role:user,content:prompt}]step_count0max_steps10whilestep_countmax_steps:print(f\n--- Step{step_count1}---)responseclient.chat.completions.create(modelself.model,messagesmessages,stop[观察:],)llm_outputresponse.choices[0].message.contentprint(f Agent:{llm_output})messages.append({role:assistant,content:llm_output})if最终答案:inllm_output:returnllm_output.split(最终答案:)[-1].strip()action_matchre.search(r行动:\s*(.*?)\n行动输入:\s*(.*),llm_output,re.DOTALL)ifaction_match:action_nameaction_match.group(1).strip()action_inputaction_match.group(2).strip()ifaction_nameintools_map:observationtools_map[action_name](action_input)else:observationfError: Tool {action_name} not found.print(f 观察:{observation})messages.append({role:user,content:f观察:{observation}})else:messages.append({role:user,content:请继续。如果你有了答案请输出 最终答案:。})step_count1returnTask limit reached without final answer.# --- 4) CLI Entrance ---if__name____main__:agentMiniReActAgent()print( Mini-ReAct Agent 已启动)print(支持工具: get_weather (模拟), calculate (计算器))print(示例: 查询北京的天气并将温度数值乘以 10)whileTrue:queryinput(\n 请输入问题 (输入 exit 退出): )ifquery.lower()in[exit,quit]:breakfinal_answeragent.chat(query)print(f\n✅ 最终答案:{final_answer})4. 如何运行在项目根目录执行python stage_02_agent_principles/project_03_mini_react/main.py可测试输入示例15 * 15 400 等于多少?查询北京的天气查询北京的天气并将温度数值乘以 105. 运行结果示例下面展示一个“多步推理”的典型输出示例为先查北京天气再把温度数值乘以 10 Mini-ReAct Agent 已启动 支持工具: get_weather (模拟), calculate (计算器) 示例: 查询北京的天气并将温度数值乘以 10 请输入问题 (输入 exit 退出): 查询北京的天气并将温度数值乘以 10 --- Step 1 --- Agent: 问题: 查询北京的天气并将温度数值乘以 10 思考: 我需要先获取北京的温度然后提取数值并进行计算。 行动: get_weather 行动输入: 北京 [系统日志] 正在查询 北京 的天气... 观察: 25°C --- Step 2 --- Agent: 思考: 已获得温度 25°C需要计算 25 * 10。 行动: calculate 行动输入: 25*10 [系统日志] 正在计算: 25*10 观察: 250 --- Step 3 --- Agent: 思考: 我现在知道最终答案了 最终答案: 北京当前温度约为 25°C温度数值乘以 10 的结果为 250。 ✅ 最终答案: 北京当前温度约为 25°C温度数值乘以 10 的结果为 250。6. 项目总结本项目用最小实现复现了 ReAct 的核心闭环模型输出行动 → 程序执行工具 → 结果回灌 → 多轮推理直至最终答案。“Stop Sequence 格式约束 正则解析”是让模型可控调用工具的关键工程组合。该实现清晰展示了 Agent 的底层机制为后续引入框架LangChain/LangGraph与更复杂的工具系统打下基础。安全提示示例中的eval()仅用于教学演示生产环境必须替换为安全计算方案否则存在严重注入风险。