🏭导航收藏不迷路—>制造业数据与AI践行者老蒋的技术博客全系列文章汇总（持续更新）
本文一次性解决以下三个连锁报错：
Invalid Format: Missing 'Action:' after 'Thought:'ValueError: Prompt missing required variables: {'tool_names'}ValueError: Prompt missing required variables: {'agent_scratchpad'}如果你正遇到其中任意一个，这篇文章就能帮你彻底解决。
📌 文章摘要
构建 LangChain ReAct Agent 时，常连续遇到 Missing 'Action:' 格式错误、tool_names 变量缺失、agent_scratchpad 转义失效三类报错。本文深入拆解根因，给出完整的正确 Prompt 模板和四条排查规则，一次性根治所有 Prompt 格式类陷阱，适用于所有 create_react_agent 项目，本地小模型场景尤其适用。
目录
第二层：{tool_names} 是 create_react_agent 的强制要求
问题现象
兄弟们，Case04 数据质量巡检 Agent （点击链接查看）的开发过程中，我遇到了一个"老朋友"——Case03 里就出现过的那种报错。
Agent 构建成功了，工具也注册了，但一运行就报：
Invalid Format: Missing 'Action:' after 'Thought:'然后 Agent 就像卡住了一样，反复尝试同样的无效输出，直到触发迭代上限：
> Finished chain.
🤖 Agent: Agent stopped due to iteration limit or time limit.我当时的第一反应是：这不科学啊……😀
明明在 Prompt 里写了格式要求，Agent 怎么就输出不了正确的格式呢？
更气人的是，改完一个报错又来一个：
ValueError: Prompt missing required variables: {'tool_names'}改完又报：
ValueError: Prompt missing required variables: {'agent_scratchpad'}同一个案例，三个格式报错，轮番轰炸。
说实话，我当时真的是把我给整没脾气了。但冷静下来之后，我发现这三个问题的根因其实是一样的——Prompt 模板的格式没写对。
根因分析
第一层：Agent 不知道"Action:"是必须的
Invalid Format: Missing 'Action:' after 'Thought:' 这个报错的字面意思是：
Agent 输出了
Thought:，但后面没有跟着Action:就直接结束了。
LangChain 的 ReActSingleInputOutputParser 解析 Agent 输出时，要求的格式是：
Thought: 你的思考
Action: 工具名称
Action Input: {"参数": "值"}
Observation: 工具返回结果
Final Answer: 最终回复如果 Agent 只输出了 Thought: 就直接写 Final Answer，解析器就会报 Missing 'Action:'。
根本原因：Prompt 模板里虽然有"格式要求"的说明，但没有给出具体的格式示例。模型不知道 Action: 是必须的，它以为可以直接跳到 Action Input: 甚至 Final Answer。
第二层：{tool_names} 是 create_react_agent 的强制要求
LangChain 的 create_react_agent 在构建 Agent 时，会从 Prompt 模板中读取两个变量：
-
{tools}→ 工具描述列表 -
{tool_names}→ 工具名称列表（用于 ReAct 的 Action 选择）
两个变量缺一不可。 只要少一个，就会报 Prompt missing required variables。
很多开发者（包括我）会在 Prompt 里写 {tools}，但很容易忘记 {tool_names}，因为 {tools} 是显眼的大段内容，而 {tool_names} 只是一行。
第三层：{agent_scratchpad} 被误转义了
{agent_scratchpad} 是 LangChain 内部用来记录 Agent 推理过程的变量，必须作为变量占位符存在。
但在写 Prompt 时，如果 JSON 示例里用了 {}，很容易顺便把 {agent_scratchpad} 也写成 {{agent_scratchpad}}（双花括号），导致它被当成纯文本而不是变量。
# ❌ 错误写法（双花括号，被当成纯文本）
Thought: {{agent_scratchpad}}
# ✅ 正确写法（单花括号，作为变量）
Thought: {agent_scratchpad}很多人遇到这个报错的第一反应是"我明明写了啊"，然后反复检查，最后发现是多打了一对花括号。 这个坑在 Case03 和 Case04 里反复出现了好几次。 可以参考之前碰到的排坑分享博客：《离谱！PromptTemplate 遇上 JSON，花括号直接引发解析战争》、《LangChain Agent 反复调用工具死循环？结构化返回 + Prompt 规则让它学会跳过》
解决方案
第一步：在 Prompt 中增加明确的格式示例
在 _get_prompt_template 中，用"正确示例"的形式展示完整格式，而不是只写"格式要求"。
def _get_prompt_template(self) -> str:
return """
你是一个数据质量巡检专家。你有权使用以下工具：
{tools}
工具名称列表: {tool_names}
**格式要求（必须严格遵守）**：
- 你必须按照以下格式输出，每一行都不能少：
Thought: 你的思考过程
Action: 工具名称
Action Input: {{}}
Observation: 工具返回结果
Final Answer: 最终回复
**正确的示例（用户说"空值检测"时）**：
Thought: 用户要求空值检测，我先加载数据
Action: load_data
Action Input: {{}}
Observation: {{"total_rows": 10000, "columns": [...]}}
Thought: 数据加载成功，继续执行空值检测
Action: null_check
Action Input: {{}}
Observation: {{"status": "ok", "alert_columns": [], "message": "空值率正常"}}
Final Answer: 空值检测完成，空值率正常，无超标列。
开始！
Question: {input}
Thought: {agent_scratchpad}
"""关键点：
-
示例中完整展示了
Thought → Action → Action Input → Observation → Final Answer的循环 -
Action:行被明确展示，模型知道它是必须的 -
示例用双花括号
{{}}转义，避免被当成变量
第二步：确保 {tool_names} 存在于模板中
在 _get_prompt_template 中，必须有一行：
工具名称列表: {tool_names}位置不重要，但必须有。建议放在 {tools} 后面，逻辑上更连贯。
第三步：检查 {agent_scratchpad} 的写法
确保结尾的 Thought: 行是：
Thought: {agent_scratchpad}而不是：
Thought: {{agent_scratchpad}}快速检查方法：在模板中搜索 {{，如果看到 {{agent_scratchpad}}，立刻改成单花括号。
完整正确模板
def _get_prompt_template(self) -> str:
return """
你是一个数据质量巡检专家。你有权使用以下工具：
{tools}
工具名称列表: {tool_names}
**核心工作流程**：
1. 根据用户指令，只执行用户要求的检测工具。
2. 执行任何检测之前，先调用 load_data。
3. 根据检测结果，给出清晰的中文结论。
**格式要求（必须严格遵守）**：
- 必须按照以下格式输出，每一行都不能少：
Thought: 你的思考过程
Action: 工具名称
Action Input: {{}}
Observation: 工具返回结果
Final Answer: 最终回复
**正确的示例**：
Thought: 用户要求空值检测，我先加载数据
Action: load_data
Action Input: {{}}
Observation: {{"total_rows": 10000, "columns": [...]}}
Thought: 数据加载成功，继续执行空值检测
Action: null_check
Action Input: {{}}
Observation: {{"status": "ok", "message": "空值率正常"}}
Final Answer: 空值检测完成，空值率正常。
开始！
Question: {input}
Thought: {agent_scratchpad}
"""修复后验证
修改后，Agent 的输出恢复正常：
🧑💻 你: 空值检测
> Entering new AgentExecutor chain...
Thought: 用户要求空值检测，我先加载数据
Action: load_data
Action Input: {}
Observation: {"total_rows": 10000, "columns": ["timestamp", "line", "temperature", "vibration", "current"]}
Thought: 数据加载成功，继续执行空值检测
Action: null_check
Action Input: {}
Observation: {"status": "ok", "alert_columns": [], "message": "空值率正常"}
Final Answer: 空值检测完成，空值率正常，无超标列。
🤖 Agent: 空值检测完成，空值率正常，无超标列。经验总结
怕你忘了，我再啰嗦一遍：LangChain ReAct Agent 的三个格式陷阱——缺少 Action:、缺少 {tool_names}、{agent_scratchpad} 被误转义——本质都是 Prompt 模板不规范导致的。
落到具体操作上就是四条排查规则：
-
Prompt 中必须有完整的格式示例：不要只写"格式要求"，要展示
Thought → Action → Action Input → Observation → Final Answer的完整循环。模型学习示例比理解指令更有效。 -
{tool_names}必须有：create_react_agent强制要求{tools}和{tool_names}两个变量同时存在。少一个就报Prompt missing required variables。 -
{agent_scratchpad}必须是单花括号：写成{{agent_scratchpad}}会被当成纯文本，导致Prompt missing required variables: {'agent_scratchpad'}。快速检查：搜索{{看有没有误转义。 -
JSON 示例用双花括号转义：变量用单花括号
{，JSON 示例用双花括号{{。这个原则适用于所有 LangChain Prompt 模板。
做制造业 AI 落地，最终拼的是底层数据架构。数仓、数据湖、湖仓一体怎么选，我将专门写一篇架构篇，结合工厂真实场景讲透了选型逻辑，感兴趣的兄弟可以延伸看看（敬请期待！）。
适用范围：
本文方案适用于所有使用
create_react_agent构建 ReAct Agent 的 LangChain 项目，尤其在使用本地小模型（Qwen2.5-7B 等）时更易触发格式问题。如果你使用的是 GPT-4 等大模型，格式问题可能不明显，但规范的模板依然是良好工程实践。再啰嗦一句：该类问题在本地 7B/14B 级开源小模型上出现概率极高；GPT-4 等闭源大模型因指令跟随能力强，触发概率较低，但规范的 Prompt 模板仍是工程化的必要要求。
系列导航
本文问题源自：《智联工坊实战：数据质量智能巡检Agent》实战过程，点击链接参考完整信息。
📋 ReAct Agent 格式报错快速自检清单
▢ Prompt 中是否包含完整的 Thought-Action-Observation 格式示例
▢ 模板中是否同时存在 {tools} 和 {tool_names} 两个变量
▢ {agent_scratchpad} 是否为单花括号，未被误转义
▢ JSON 示例是否用双花括号 {{}} 完成转义
💡 建议收藏：遇到 LangChain Agent 格式报错时，优先对照本文的三条排查规则检查 Prompt 模板。90% 的问题都出在这三个点上——Action: 缺失、{tool_names} 缺失、{agent_scratchpad} 被转义。
互动与交流
兄弟们，这三个格式坑你踩过几个？
A. 只踩过 Missing Action
B. tool_names 缺失卡过我
C. agent_scratchpad 转义坑最隐蔽
D. 三个全中，简直是报错三连击
评论区扣选项，我选 3 位兄弟，发 ReAct Agent 标准 Prompt 通用模板。
关于作者
制造业数据与 AI 践行者老蒋，23 年 IT 老兵。聚焦制造业数据架构与 AI 融合落地。全流程实战，全源码开源。
标签：#排坑笔记 #LangChain #Agent #ReAct Agent #Missing Action报错 #Prompt模板 #agent_scratchpad #工具调用排坑
扫一扫
402
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
