导航收藏不迷路—制造业数据与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 项目本地小模型场景尤其适用。目录问题现象根因分析第一层Agent 不知道Action:是必须的第二层{tool_names} 是 create_react_agent 的强制要求第三层{agent_scratchpad} 被误转义了解决方案第一步在 Prompt 中增加明确的格式示例第二步确保 {tool_names} 存在于模板中第三步检查 {agent_scratchpad} 的写法完整正确模板修复后验证经验总结系列导航互动与交流关于作者问题现象兄弟们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 模板仍是工程化的必要要求。系列导航本文属于《数据与AI工程排坑笔记》系列上一篇智联工坊实战数据质量智能巡检Agent让AI帮你发现脏数据下一篇《数仓储不了视频数据湖管不好质量制造企业湖仓一体架构详解》本文问题源自《智联工坊实战数据质量智能巡检Agent》实战过程点击链接参考完整信息。 ReAct Agent 格式报错快速自检清单▢ Prompt 中是否包含完整的 Thought-Action-Observation 格式示例▢ 模板中是否同时存在 {tools} 和 {tool_names} 两个变量▢ {agent_scratchpad} 是否为单花括号未被误转义▢ JSON 示例是否用双花括号 {{}} 完成转义建议收藏遇到 LangChain Agent 格式报错时优先对照本文的三条排查规则检查 Prompt 模板。90% 的问题都出在这三个点上——Action:缺失、{tool_names}缺失、{agent_scratchpad}被转义。互动与交流兄弟们这三个格式坑你踩过几个A. 只踩过 Missing ActionB. tool_names 缺失卡过我C. agent_scratchpad 转义坑最隐蔽D. 三个全中简直是报错三连击评论区扣选项我选 3 位兄弟发 ReAct Agent 标准 Prompt 通用模板。关于作者制造业数据与 AI 践行者老蒋23 年 IT 老兵。聚焦制造业数据架构与 AI 融合落地。全流程实战全源码开源。标签#排坑笔记#LangChain#Agent#ReAct Agent#Missing Action报错#Prompt模板#agent_scratchpad#工具调用排坑