引言：

我一开始做 Agent 时，最大的问题不是模型不聪明，

而是——我不知道它到底在“想”，还是已经在“编答案”。

后来我意识到，我缺的不是更复杂的 Prompt，

而是一个能把“思考”和“行动”拆清楚的结构—— ReAct。

为什么学习经典架构？

Agent框架确实解决了工程化中的很多脏活累活比如工具集成，模型切换，Memory自动化裁剪等等，

但如果你一上来就用框架，并不能够很好的理解Agent的思考过程，

后续开发过程中遇到Bug难以排查，容易变成“调包侠”

简单来说：经典架构是“内功心法”，框架是“兵器”。如果你不理解架构原理，在使用框架时就会像在黑盒里

调参，一旦 Agent 陷入死循环或任务失败，你将无从下手。

所以学习ReAct, Plan-and-Solve 等经典架构是非常重要的

那么本篇文章将会对ReAct架构进行深度拆解分析。

ReAct 的核心循环：Thought -> Action -> Observation

ReAct 运行起来就像一个不停旋转的轮子，包含三个步骤：

① Thought (思考)

模型描述当前的情况、目标以及下一步该做什么。

• 例子：“我已经搜到了姚明的身高，但我还需要搜到奥尼尔的身高才能进行对比。”

② Action (行动)

模型根据思考做出决策，调用具体的工具（API）。

• 例子：Search[奥尼尔身高]

③ Observation (观察)

系统执行工具后，将结果反馈给模型。

• 例子：“奥尼尔的身高是 2.16 米。”

模型看到 Observation 后，会再次进入 Thought 阶段，判断任务是否完成。如果不满意，就继续循环。

了解了整体架构，该怎么实现这些具体功能呢？

架构总览

.envllm.py #封装大语言模型客户端main.py #Agent的“启动器”prompt.pyReActAgent.py #ReAct流程tools.py #可调用的外部工具

main.py 解析：ReAct 智能体的“组装与启动”

在整个工程中，main.py是程序的入口点。它的核心逻辑遵循了构建 AI Agent 的经典四步法：

“大脑初始化 -> 手脚（工具）挂载 -> 躯干（Agent）组装 -> 任务下发”。

我们可以将代码拆解为以下几个关键阶段：

1. 引入核心组件 (Imports)

Pythonfrom llm import DeepSeekClient from tools import ToolExecutor from ReActAgent import ReActAgent

从项目结构图中可以看到，这三行代码分别引入了 ReAct 架构的三个支柱：

1.DeepSeekClient**(大脑)**：负责与大模型（这里是 DeepSeek）进行通信，提供推理能力。

2.ToolExecutor**(手脚)**：负责管理和调用外部工具（如搜索功能）。

3.ReActAgent**(中枢)**：核心类，它定义了“思考-行动-观察”的循环逻辑。

2. 初始化基础设施 (Step 1)

Python# 初始化DeepSeek客户端和工具执行器 deepseek_client = DeepSeekClient() tool_executor = ToolExecutor()

这里实例化了底层的“原子能力”。此时，LLM 只是一个 API 接口，工具执行器也只是一个空的工具箱，两者还互不认识。

3. 注册工具能力 (Step 2)

Python# 注册Tavily网页搜索工具 tool_executor.register_tool( ``````plaintext name="web_search", ``````plaintext description="使用Tavily进行网页搜索以获取最新信息。", ``````plaintext func=tool_executor.search_web )

这是 ReAct 架构中非常关键的一步——赋予能力。

• 我们向工具箱中放入了名为 web_search 的工具。
• 注意：
• 这里的description至关重要。在 ReAct 模式中，Agent 是通过读取这个描述来决定“什么时候该用这个工具”。

4. 组装 ReAct 代理 (Step 3)

Python# 初始化ReAct代理 react_agent = ReActAgent( deepseek_client=deepseek_client, ``````plaintext tool_executor=tool_executor, ``````plaintext max_steps=5 )

这是依赖注入的体现。我们将“大脑”和“工具箱”注入到ReActAgent中。

• max_steps=5

  是一个安全机制，防止 Agent 陷入“思考-行动”的死循环（例如反复搜索同一个词）。

5. 任务下发与执行 (Step 4)

Pythonquestion = "请告诉我2025年最新的人工智能发展趋势？" final_answer= ``````plaintext react_agent.run(question)

Prompt 触发：虽然代码里只有一行question，但实际上react_agent.run()内部会将这个问题通过prompt.py中的模板封装成 ReAct 格式的 Prompt 发送给 LLM。

闭环：程序等待 Agent 完成多轮的“推理->搜索->再推理”，直到返回final_answer。

灵魂深处（Prompt Engineering）：

这部分内容非常精彩，因为它触及了 ReAct Agent 开发中最“玄学”但也最核心的部分

——提示词工程（Prompt Engineering）。

在 ReAct 架构中，Python 代码只是骨架，Prompt 才是灵魂。如果 Prompt 写得不好，

Agent 就会变成一个胡言乱语的疯子，或者一个不停重复动作的傻瓜

在 ReAct 架构中，LLM 本质上是一个续写机器。我们需要通过这段 Prompt，

强行将一个“只会说话的文科生”训练成一个“懂逻辑、会调用工具的理科生”。

解析promt.py

这段REACT_PROMPT_TEMPLATE看起来简单，实际上包含了三个关键指令区：

能力注入区 ({tools})：

# 动态插入工具描述 {tools}

这里是 Agent 知道自己“能干什么”的唯一来源。

main.py 里注册的 web_search 及其描述，最终都会被填入这里。

思维链协议 (The Loop Protocol)：

Question: ... Thought: ... Action: ... Observation: ...

这是 ReAct 的核心心法。我们强制要求模型

“想一步（Thought），做一步（Action）”。

关键点：Observation: (🛑 绝不要自己生成这部分！...)。

这句话是防止**幻觉（Hallucination）**的关键。如果没有这句警告，

LLM 经常会自己假装搜索，然后编造一个搜索结果（Observation），导致整个逻辑崩塌。

状态注入区 ({history}&{question})：

这是 Agent 的“短期记忆”。{history}保存了之前的思考和行动轨迹，

让 LLM 知道自己进展到了哪一步。

💡 踩坑实录：模型为何“不听话”？
在开发过程中，我遇到了一个典型的问题：模型输出格式错误。
❌ 问题重现：起初，我的 Prompt 指引性不够强。当 Agent 进行推理时，
它经常会把Thought和Action混在同一行输出，或者遗漏关键字。

例如，模型输出了这样的内容：

Thought: 我需要搜索一下2025年的AI趋势 Action: web_search[“2025 AI trends”]

💥 后果：后端的 Python 正则表达式（Regex）解析器原本期待的是：

1. 先抓取Action:标记。
2. 再提取后面的内容。 当它们粘连在一起时，解析器无法识别，导致 Agent 报错或陷入死循环（一直在思考，从未行动）。

✅ 解决方案：强制换行约束为了解决这个问题，我优化了REACT_PROMPT_TEMPLATE，增加了显式的格式指引。

修改前的指令：

请严格遵守以下格式进行输出…

修改后的指令（增加了“换行”强调）：

请严格遵守以下格式进行输出（注意：Action 必须在 Thought 之后另起一行开始）：

甚至可以在模板示例中通过换行符强化这一印象。这种“给大模型立规矩”的过程，

本质上就是用自然语言在进行编程。

Python# 优化后的模板片段 REACT_PROMPT_TEMPLATE = """ ... 请严格遵守以下格式（每个阶段必须换行）： Question: 用户的问题 Thought: 思考下一步做什么 Action: 工具名称[参数] <-- 强调这里单独一行，或者保持 Action: 工具名称[参数] 但确保前面有换行 ... """

总结：prompt.py不仅仅是字符串拼接，它是连接自然语言推理（LLM）与 确定性代码执行（Python）的桥梁。任何格式上的模糊，都会导致这座桥梁的断裂。

Agent Loop

ReActAgent.py是整个工程中最复杂、也是含金量最高的文件。

它通过一个while循环，维持着智能体的生命周期。

我将这个文件拆解为三个关键维度：

记忆构建、感知解析、行动反馈。而每一个维度背后，都有我亲历的“坑”。

1.记忆构建

在run函数的循环中，有一行看似不起眼的代码，却决定了 Agent 的智商上限：

Python# 关键：记录 Thought，让 LLM 保持逻辑连贯 if thought: self.history.append(f"Thought: {thought}")

💥 踩坑实录：历史记录丢失 Thought

现象：起初我只记录了Action和Observation（工具返回结果）。结果发现 Agent 经常陷入死循环，比如反复搜索同一个关键词，或者逻辑突然断层。

原因：LLM 是无状态的。如果不在history中把它的Thought（思考过程）传回给它，它就忘记了自己“为什么”要执行上一步操作。它会像一个重度健忘症患者，每一步都是新的开始。

解决：必须将Thought显式加入self.history。这相当于给了 Agent 一个“工作记忆”，让它知道自己的推理路径。

2. 感知解析：与“脆弱”的正则搏斗 (The Regex Pitfall)

LLM 输出的是自然语言，而程序需要的是结构化指令。这就需要_parse_output方法来充当“翻译官”。

Pythondef _parse_output(self, text: str): # 使用 re.DOTALL 使得 . 可以匹配换行符 thought_pattern = r"Thought:\s*(.*?)(?=\s*Action:|$)" ``````plaintext thought_match=re.search(thought_pattern, text, re.DOTALL) ...

💥 踩坑实录：正则太脆弱

现象：当模型通过思维链（Chain of Thought）进行长篇大论的分析时，它往往会换行。

模型输出：Thought: 我需要先搜索 A。\n 然后再搜索 B。

旧代码：re.search(r"Thought: (.*)", text)

后果：Python 的正则.默认不匹配换行符。这导致解析器只能抓取到第一行，甚至直接解析失败，丢掉了关键的推理信息。

改进：引入re.DOTALL标志位。它告诉正则引擎：“请把换行符也当作普通字符处理”。这是一个极小的改动，但极大地提升了 Agent 的鲁棒性。

3. 行动反馈：拥抱错误 (The Error Handling Pitfall)

在执行工具时，我们必须假设“一切皆有可能出错”。

Pythontry: tool_name,tool_param= self._parse_action(action) ``````plaintext tool_func=self.tool_executor.get_tool(tool_name) ``````plaintext if tool_func: observation = tool_func(tool_param) else: observation=f"Error:Tool {tool_name} not found." except Exception as e: observation = f"Error during tool execution: {e}"

💥 踩坑实录：工具报错导致程序崩溃

现象：假设 Agent 想要搜索，但网络断了，或者参数填错了。早期的代码会直接抛出 Python Exception，导致整个main.py进程终止。

思考：人类在使用工具失败时（比如网页打不开），会直接晕倒吗？不会，我们会刷新一下，或者换个网站。Agent 也应如此。

解决：使用try...except捕获所有工具执行层面的异常。

关键点：不要只是打印错误，而是要将错误信息作为Observation返回给 LLM。

效果：当 LLM 看到Observation: Error during tool execution...时，它会根据 ReAct 逻辑进行自我修正（Self-Correction），尝试更换参数或使用其他工具。这才是真正的“智能”

基础设施与性能优化（Tools & LLM）

如果说ReActAgent.py是逻辑中枢，那么llm.py和tools.py就是支撑它运行的物理底座。
这一层最容易被忽视，但 90% 的“程序卡死”或“API 超时”问题都发生在这里。

1. llm.py：给大模型装上“刹车片”

llm.py的核心任务是封装 DeepSeek（或其他兼容 OpenAI 格式的模型）的 API 调用。

这里有一个极容易被忽略、但对 ReAct 至关重要的参数：stop。

Pythonresponse= self.client.chat.completions.create( ... stop=["Observation:", "Observation"] # 🛑 关键刹车片 )

• 为什么需要它？

ReAct 的模式是

• Thought -> Action ->Observation。
• Thought和Action

是由LLM生成的。

• Observation

  是由代码（工具）执行后返回的。

• 如果没有stop参数，LLM 经常会“自作聪明”，在生成完Action后，自己编造一个假的Observation，导致程序根本没有机会去调用真正的搜索工具。

• 设置stop=["Observation:"]，就是告诉 LLM：“写到这里就停笔！剩下的交给（程序）来填。”

2. tools.py：Tavily 搜索的防爆处理

tools.py实现了一个标准的工具注册模式（Registry Pattern），方便后续扩展天气查询、股票接口等。

但最值得讲的，是对search_web函数的“防卡死优化”。

💥 踩坑实录：搜索结果撑爆系统

现象：程序运行到“搜索”步骤时，经常莫名卡住，或者报错ReadTimeout/SSL Error。

原因分析：Tavily（以及类似的搜索 API）在默认情况下，可能会返回包含大量网页杂讯（HTML 标签、无关广告文案）的content。有时候一个搜索结果就包含 10,000+ 字符。

双重打击：

网络层：巨大的 JSON 包在弱网环境下下载极慢，导致 Pythonrequests库读取超时。

模型层：即使下载下来了，把 10,000 字塞进 Prompt 发给 DeepSeek，不仅消耗 Token 钱，还会导致模型首字推理延迟（TTFT）飙升，甚至超过 API 的 timeout 限制。

🛠️ 解决方案：三级“节流阀”为了解决这个问题，代码中实施了三级流量控制，这是工程化落地的典范：

1.源头减负：

Python# 限制只返回 3 条结果，且使用 "basic" 深度（只抓摘要，不抓全文）response=self.tavily.search(query=query,max_results=3,search_depth="basic")

2.精细化提取： 不要直接把整个 JSON 扔给 LLM。代码中只提取了title、url和content，构建了干净的字符串。

3.暴力截断（保底机制）： 这是最实用的一招。无论搜索结果多长，强制砍刀。

Python# 🛑 强制截断 (防止下一次 LLM 调用卡死) if len(final_result) > 2000: final_result = final_result[:2000] + "\n...(内容过长已截断)"

经验之谈：对于 ReAct 任务，2000 字符的上下文通常足够模型提炼关键信息了。保留系统的响应速度比追求“全量信息”更重要。

总结与展望：从 Demo 到实战的跨越

至此，我们已经亲手搭建了一个基于DeepSeek + ReAct架构的最小化 AI Agent 系统。
回顾整个过程，你会发现，写代码（Coding）其实只占了工作量的一小部分，更多的时间我们是在做“调教（Alignment）”和“填坑（Engineering）”。

核心复盘

很多人觉得 AI Agent 就是import openai那么简单，但通过这篇文章的实战拆解，我们看到了真相：

Prompt 是隐形的接口：prompt.py中一句简单的“请换行输出”，决定了整个系统的稳定性。自然语言编程（Natural Language Programming）不再是空话，而是对逻辑严密性的极致考验。

鲁棒性是可用的前提：在ReActAgent.py中，如果我不去处理正则匹配的re.DOTALL问题，如果我不去在tools.py里给 Tavily 的搜索结果做截断，这个 Agent 也就是个只能在演示视频里存活的“玩具”。

闭环是智能的源头：Thought -> Action -> Observation的循环，配合history的记忆管理，让大模型第一次拥有了“反思”和“修正”的能力。

2. 未来展望：如何让它更聪明？

目前的main.py只是一个起点。在这个地基之上，我们还有无限的扩展空间，以下是我接下来的迭代计划（也是留给大家的思考题）：

方向一：长短期记忆（RAG + Vector DB）现在的 Agent 只有“金鱼记忆”，对话一长就会超出 Token 限制。下一步，我们可以引入RAG（检索增强生成）技术，给它挂载一个向量数据库作为“海马体”，让它能记住上周的对话或私有的知识库。

方向二：工具箱扩容（Code Interpreter）目前它只会搜索。想象一下，如果我们给它装上 Python 解释器（Sandbox），让它不仅能“读”网页，还能“写”代码来画图、分析 Excel 数据，它的能力将呈指数级增长。

方向三：多智能体协作（Multi-Agent）一个 ReAct Agent 既当爹又当妈（既规划又执行）容易精神分裂。未来我们可以参考 MetaGPT 或 AutoGen 的思路，拆分出“产品经理 Agent”负责规划，“工程师 Agent”负责写代码，“测试 Agent”负责找 Bug，让 AI 团队化作战。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】