阶段4（上）：LangGraph、Function Calling、MCP（SDK 2.x）、Agent 评测与运维、Agent 设计专题；run_examples 设置 RUN_EXAMPLES=1

topics/ai/agent-design/01-react-planning.md

@@ -0,0 +1,92 @@
+---
+id: ai.agent-design.react-planning
+title: Agent 推理模式：ReAct、Plan-and-Execute、反思和 Agentic RAG
+type: lesson
+domain: ai
+stack: [agent-design]
+tags: [ReAct, Plan-and-Execute, 规划, 反思, Agentic RAG, 工作流 vs Agent]
+level: intermediate
+prerequisites: [ai.function-calling.tool-loop]
+est_hours: 3
+related: [ai.agent-design.context-skills-multiagent, ai.langgraph.state-graph, ai.agent-design.interview]
+week: [10, 11]
+order: 1
+---
+
+# Agent 推理模式：ReAct、Plan-and-Execute、反思和 Agentic RAG
+
+## 解释说明
+
+### 先问：真的需要 Agent 吗？
+
+| 形态 | 特点 | 适合 |
+| --- | --- | --- |
+| 单次调用 | 一个提示词一次输出 | 分类、提取、改写 |
+| **工作流（Workflow）** | 步骤由代码固定，模型只完成其中的环节 | 流程明确的业务：工单分类 → 起草 → 审批 |
+| **Agent** | 模型自己决定下一步做什么、调用什么工具、何时结束 | 步骤不固定、需要探索的任务：排查问题、调研、复杂查询 |
+
+企业里大多数需求用工作流就够了，更可控、更便宜、更好评测。Agent 用在确实需要灵活性的地方，并且要有步数、预算、权限的边界。面试时能说出这个判断，比背模式名更重要。
+
+### 常见模式
+
+| 模式 | 做法 | 优点 | 缺点 |
+| --- | --- | --- | --- |
+| **ReAct**（推理 + 行动） | 循环：思考 → 调用工具 → 观察结果 → 再思考，直到给出答案 | 简单通用，现代工具调用 Agent 基本都是这个循环 | 每步都调用大模型，长任务容易跑偏 |
+| **Plan-and-Execute**（先规划后执行） | 先生成完整计划（步骤列表），再逐步执行；失败时把错误反馈给规划器重新规划 | 全局视角，步骤可展示给用户确认，执行步骤可以用便宜模型 | 计划可能不切实际，需要重新规划机制 |
+| **反思（Reflection）** | 生成后让模型（或另一个模型）按标准检查并修改 | 提升质量 | 成本和延迟翻倍；检查标准要明确 |
+| **Agentic RAG** | 由 Agent 决定是否检索、改写查询、多次检索、选择数据源、检查答案是否有依据 | 能处理多跳、模糊问题 | 延迟高，必须有最大步数 |
+
+### 规划的工程要点
+
+- 计划用**结构化输出**（步骤列表：工具、参数、依赖），而不是自由文本。
+- 每一步有状态（待执行 / 完成 / 失败），可展示、可恢复（用 LangGraph 检查点）。
+- 失败时把**具体错误**反馈给规划器；设置最大重新规划次数，超过后转人工。
+- 有副作用的步骤在执行前让用户确认计划。
+
+## 案例
+
+运营人员说“生成 9 月各大区销售报表并发给运营组”。Plan-and-Execute：规划出“查询销售数据 → 生成图表 → 发送”三步并展示给用户；第一次查询因为缺少月份参数失败，错误反馈给规划器后修正参数，第二次执行成功。整个过程每一步的状态都在界面上可见。
+
+## 代码示例
+
+完整可运行版本：[examples/agent-patterns/patterns.py](examples/agent-patterns/patterns.py)。Plan-and-Execute 核心：
+
+```python
+def plan_and_execute(goal: str, max_replans: int = 2):
+    log, feedback = [], None
+    for attempt in range(max_replans + 1):
+        steps = plan(goal, feedback)                 # 真实项目：大模型输出结构化计划
+        for s in steps:
+            s.result = TOOLS[s.tool](s.args)
+            if "error" in s.result:
+                s.status = "failed"
+                feedback = f"{s.tool} 失败：{s.result['error']}"   # 具体错误反馈给规划器
+                break
+            s.status = "done"
+        else:
+            return steps, log                        # 全部成功
+    return steps, log + ["超过最大重新规划次数，转人工"]
+```
+
+输出：
+
+```text
+第 1 次规划：['query_sales', 'make_chart', 'send_report']
+query_sales 失败：缺少 month 参数
+第 2 次规划：['query_sales', 'make_chart', 'send_report']
+最终步骤状态： [('query_sales', 'done'), ('make_chart', 'done'), ('send_report', 'done')]
+```
+
+## 易错点
+
+- 所有需求都做成 Agent：流程固定的用工作流。
+- 没有最大步数 / 最大重新规划次数，失败时无限循环、成本失控。
+- 计划是自由文本，无法校验和展示。
+- 反思步骤没有明确标准（“检查一下有没有问题”），模型只会说“没问题”。
+- 只测最终答案，不测中间过程（工具调用序列、步数）。
+
+## 面试常问
+
+- ReAct 是什么？和 Plan-and-Execute 有什么区别？
+- 工作流和 Agent 怎么选？
+- Agentic RAG 和普通 RAG 的区别？