1. 项目概述当LLM代理学会“结构化反思”最近在折腾LLM驱动的智能体Agent时我遇到了一个几乎所有开发者都会头疼的问题任务执行链条一旦出错代理就像个固执的程序员只会用同样的错误逻辑反复尝试陷入死循环。比如你让它写一段代码它第一次可能因为某个库的导入路径不对而失败第二次、第三次它还是会用同样的错误路径去尝试而不是停下来思考“我上次为什么错了”。这让我开始思考如何让LLM代理具备类似人类的“复盘”能力从而显著提升其任务修复的成功率。“Structured Feedback Improves Repair in an LLM Agent Loop”这个标题精准地指向了解决这个痛点的核心思路结构化反馈。它不是一个简单的“重试”按钮而是一套引导LLM代理进行系统性自我诊断和修正的机制。简单来说就是把一次失败的执行结果从一堆杂乱无章的错误信息整理成一份清晰的“病历报告”然后让代理根据这份报告有针对性地开出“药方”。这个过程我们称之为“修复循环”。这个思路的价值在于它跳出了单纯依赖更大模型或更复杂提示工程的框架转而关注如何优化LLM与外部环境如代码执行器、API、数据库交互过程中的信息流质量。对于任何构建LLM应用尤其是涉及多步骤推理、工具调用和状态维护的Agent系统开发者来说理解并实现有效的结构化反馈循环是提升系统鲁棒性和实用性的关键一步。2. 核心思路拆解从“试错”到“循证修复”传统的LLM Agent在执行失败后常见的处理方式是把原始错误信息比如Python的Traceback直接塞回给LLM并附上一句“请修复错误后重试”。这种方式存在几个明显缺陷信息过载与噪声原始错误堆栈通常包含大量与核心问题无关的细节如内部库的调用路径会干扰LLM的判断。缺乏上下文关联LLM很难自动将错误信息与它之前做出的具体决策如选择了哪个工具、传入了什么参数联系起来。修复方向模糊没有引导LLM的修复尝试可能是盲目的可能修改了正确的部分而忽略了真正的错误根源。结构化反馈的核心思想就是充当一个“信息过滤器”和“问题引导员”。它的目标不是替LLM解决问题而是帮它更好地理解问题。我们可以把这个过程分解为几个关键环节2.1 反馈的结构化从原始错误到诊断清单首先我们需要定义一个“结构化”的模板。这个模板将杂乱的执行结果转化为几个明确的维度。一个基础的模板可能包括执行状态成功、失败、超时、部分成功。关键错误信息提炼自Traceback的核心错误类型和消息如ModuleNotFoundError: No module named requests。错误定位发生在哪个步骤调用了哪个工具或函数相关上下文导致错误的输入参数是什么当前的环境状态如工作目录、已加载的变量是怎样的可能的原因假设基于常见模式自动生成几个最可能的错误原因如依赖缺失、权限不足、参数类型错误。例如一个执行pip install失败的原始输出可能是上百行的日志。经过结构化我们得到状态失败关键错误ConnectionError: Failed to establish a new connection定位步骤2 - 执行Shell命令pip install some-package上下文网络代理设置未知当前为离线环境可能原因网络连接问题包名拼写错误pip源不可用。2.2 修复策略的生成基于结构的推理拿到结构化反馈后LLM的提示词Prompt就从“修复这个错误”变成了更具指导性的任务 “基于以下诊断报告请生成修复策略。报告指出错误原因为‘网络连接问题’发生在‘安装依赖’步骤。请首先验证网络连通性如果失败则建议检查代理设置或切换pip源。请输出具体的、可执行的修正步骤。”这种方式极大地约束了LLM的思考空间让它聚焦于最有可能的解决路径上减少了“胡思乱想”的概率。2.3 循环的构建迭代与验证单次修复尝试可能不足以解决问题。结构化反馈循环意味着这个过程可以迭代进行。第二次的反馈会包含第一次修复动作及其结果形成更丰富的上下文。例如 “第一次修复策略‘切换pip源’已执行但错误变为‘包版本不匹配’。新的诊断报告如下...” 通过迭代Agent能够进行更深入的因果推理逐步逼近正确解决方案。注意结构化模板的设计需要与你的具体任务领域高度相关。编写代码、操作数据库、调用API它们的错误模式和诊断维度是不同的。没有放之四海而皆准的模板。3. 实现一个基础的结构化反馈修复循环理论说再多不如动手实现一个。下面我将以一个“Python脚本编写与执行Agent”为例展示如何构建一个最简单的结构化反馈修复循环。这个Agent的任务是根据用户需求生成Python脚本并执行它如果执行失败则尝试修复。3.1 系统组件设计我们需要几个核心组件任务规划与执行器LLM负责理解任务、生成代码或命令。代码/命令执行器一个安全的沙箱环境用于运行生成的代码并捕获输出。反馈结构化引擎分析执行器的原始输出生成结构化诊断报告。修复协调器LLM根据诊断报告规划修复步骤。状态追踪器维护整个循环的历史原始任务、已执行动作、历史反馈。3.2 关键代码实现与解析我们使用Python和LangChain框架来简化构建过程。假设我们已经有一个基础的ReAct风格Agent。首先定义我们的结构化反馈模板这里用Pydantic模型来保证结构from pydantic import BaseModel, Field from enum import Enum class ExecutionStatus(str, Enum): SUCCESS “success” FAILURE “failure” TIMEOUT “timeout” class StructuredFeedback(BaseModel): 执行结果的结构化反馈 status: ExecutionStatus primary_error: str Field(description“最核心的错误描述一行概括”) error_location: str Field(description“错误发生在哪个阶段或哪行代码附近”) raw_output_snippet: str Field(description“原始输出中最相关的片段”) possible_root_causes: list[str] Field(description“基于经验列举的潜在根本原因”) context_snapshot: dict Field(description“错误发生时的关键上下文快照如变量值、工作目录”)接着实现反馈结构化引擎。这是一个启发式规则与轻量级LLM调用结合的部分。对于简单错误可以用规则匹配对于复杂错误可以用一个小模型如GPT-3.5-turbo来解析。import re from langchain.chat_models import ChatOpenAI from langchain.schema import HumanMessage class FeedbackStructurer: def __init__(self): # 可以初始化一个快速LLM用于复杂解析 self.llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) # 预编译一些常见错误模式的正则表达式 self.error_patterns { “ModuleNotFoundError”: r“ModuleNotFoundError: No module named ‘([^’])’“, “ImportError”: r“ImportError: ([^\n])”, “SyntaxError”: r“SyntaxError: ([^\n])”, “ConnectionError”: r“ConnectionError: ([^\n])”, } def structure(self, raw_output: str, execution_context: dict) - StructuredFeedback: 将原始输出转化为结构化反馈 feedback StructuredFeedback(statusExecutionStatus.SUCCESS, primary_error“”, error_location“”, raw_output_snippet“”, possible_root_causes[], context_snapshotexecution_context) # 1. 判断状态 if “Traceback (most recent call last):” in raw_output: feedback.status ExecutionStatus.FAILURE elif “Execution timed out” in raw_output: feedback.status ExecutionStatus.TIMEOUT # ... 其他状态判断 if feedback.status ! ExecutionStatus.SUCCESS: # 2. 提取核心错误规则优先 primary_error, error_type self._extract_primary_error(raw_output) feedback.primary_error primary_error feedback.raw_output_snippet self._extract_relevant_snippet(raw_output) # 3. 定位错误位置从Traceback中提取 feedback.error_location self._extract_error_location(raw_output) # 4. 生成可能的原因结合规则和LLM feedback.possible_root_causes self._infer_root_causes(error_type, primary_error, execution_context) return feedback def _extract_primary_error(self, raw_output: str) - tuple[str, str]: for error_name, pattern in self.error_patterns.items(): match re.search(pattern, raw_output) if match: return f“{error_name}: {match.group(1)}“, error_name # 如果规则匹配不上使用LLM进行提取 prompt f“””请从以下程序错误输出中提取最核心的一行错误描述并指出错误类型如语法错误、导入错误、运行时错误等。 输出格式为“错误类型: 错误描述” 输出 {raw_output[-1000:]} # 只取最后一部分避免token过长 “”” response self.llm([HumanMessage(contentprompt)]) return response.content, “Unknown” def _extract_error_location(self, raw_output: str) - str: # 简化提取Traceback中最后一个用户文件的路径和行号 lines raw_output.split(‘\n’) for line in reversed(lines): if ‘File “‘ in line and ‘line ‘ in line: # 提取类似 “File “/tmp/script.py”, line 5, in module” 的信息 return line.strip() return “Unknown location” def _infer_root_causes(self, error_type: str, error_msg: str, context: dict) - list[str]: causes [] # 基于错误类型的启发式规则 if error_type “ModuleNotFoundError”: causes.append(“缺少Python依赖包”) causes.append(“模块名称拼写错误”) causes.append(“Python环境路径配置不正确”) elif “Connection” in error_type: causes.append(“网络连接失败”) causes.append(“目标服务不可用”) causes.append(“防火墙或代理设置阻止了连接”) # ... 更多规则 # 可以在此处加入LLM调用基于更具体的错误信息生成原因 return causes[:3] # 返回最相关的2-3个然后我们需要增强修复协调器的提示词。这是循环的核心大脑。REPAIR_AGENT_PROMPT “”” 你是一个代码问题修复专家。以下是当前任务的上下文和最新一次执行失败的结构化诊断报告。 **历史任务目标** {task_description} **已执行的操作历史** {action_history} **最新的结构化诊断报告** - 状态{feedback.status} - 核心错误{feedback.primary_error} - 错误位置{feedback.error_location} - 可能的原因{‘ ‘.join(feedback.possible_root_causes)} - 上下文快照{feedback.context_snapshot} 请根据诊断报告制定下一步的修复计划。你的输出必须是纯JSON格式包含以下两个字段 1. reasoning: 你的推理过程分析最可能的原因是什么以及为什么选择接下来的修复动作。 2. action: 具体、可执行的修复动作描述。这应该是一个可以直接由执行器运行的命令或代码片段。如果是修改代码请给出完整的修正后代码块。 **注意**你的修复动作必须针对诊断报告中指出的“可能的原因”。避免做出与当前错误无关的改动。 “””最后构建主循环逻辑class SelfRepairingAgent: def __init__(self, task_agent, executor, structurer, max_retries3): self.task_agent task_agent # 初始任务规划Agent self.executor executor # 代码执行器 self.structurer structurer # 反馈结构化引擎 self.max_retries max_retries self.history [] def run(self, user_query: str): print(f“开始任务: {user_query}“) current_plan user_query for attempt in range(self.max_retries 1): # 1 包含第一次尝试 print(f“\n 尝试第 {attempt 1} 次 ”) # 1. 生成代码或动作 if attempt 0: action_to_take self.task_agent.generate_initial_plan(current_plan) else: # 非首次尝试使用修复协调器 last_feedback self.history[-1][‘feedback’] repair_prompt REPAIR_AGENT_PROMPT.format(...) # 填充变量 action_to_take self.repair_agent.generate(repair_prompt) self.history.append({‘attempt’: attempt, ‘action’: action_to_take}) # 2. 执行 raw_output, exec_context self.executor.execute(action_to_take) print(f“执行输出:\n{raw_output[:500]}...”) # 打印前500字符 # 3. 结构化反馈 feedback self.structurer.structure(raw_output, exec_context) self.history[-1][‘feedback’] feedback print(f“结构化诊断: {feedback.status} - {feedback.primary_error}“) # 4. 判断是否成功或继续 if feedback.status ExecutionStatus.SUCCESS: print(“任务成功完成”) return raw_output, self.history elif attempt self.max_retries: print(“达到最大重试次数任务失败。”) break else: print(“根据诊断报告进入修复循环...”) # 循环继续 return None, self.history # 返回失败3.3 实操心得与配置要点执行器的安全性是重中之重如果Agent能执行任意Shell命令或代码必须将其放在严格的沙箱中如Docker容器、subprocesswithtimeout、restrictedpython。永远不要在生产环境直接运行未经审查的LLM生成代码。结构化引擎的规则需要持续维护初期可以主要依赖LLM进行解析但随着任务固定你会发现80%的错误是那20%的常见类型。为这些常见错误编写精确的正则表达式或规则能大幅降低延迟和成本。修复协调器的提示词需要精心调试REPAIR_AGENT_PROMPT中的指令清晰度直接决定修复效果。明确要求输出JSON格式并指定reasoning字段这不仅能得到结构化结果还能在调试时看到LLM的“思考过程”便于优化。控制循环次数与成本max_retries不宜设置过大3-5次通常是合理的。每次循环都消耗Token和API调用需在成功率和成本间取得平衡。可以考虑设置“总Token数”或“总耗时”上限。4. 高级策略与优化方向实现基础循环后我们可以从以下几个方向进行优化让修复更加智能和高效。4.1 反馈结构的动态演进最初的反馈模板是静态的。更高级的做法是让模板本身也能根据历史经验进化。例如系统可以记录某种错误类型如ConnectionError最常关联的成功修复动作是什么如“重试”、“切换代理”。当possible_root_causes中的某个原因被多次排除后可以降低其在未来列表中的优先级。这可以通过一个轻量级的记忆模块或向量数据库来实现将历史诊断-修复对存储和检索起来用于优化后续的反馈生成和修复建议。4.2 多模态反馈的整合对于更复杂的Agent其反馈不限于文本。还可能包括截图或图像对于操作图形界面的自动化Agent失败时可能伴随错误弹窗的截图。日志文件大型应用会产生独立的日志文件。结构化数据JSON/XMLAPI调用返回的错误码和消息。我们的结构化引擎需要能处理这些多模态输入。例如可以先用视觉模型如GPT-4V描述截图内容将其转化为文本再与日志文本一同输入给文本分析模块进行综合诊断。4.3 修复策略的分层与回退不是所有错误都值得进入复杂的修复循环。可以设计一个分层策略Level 1: 自动重试对于网络超时等瞬时错误立即自动重试1-2次。Level 2: 简单规则修复对于“模块未找到”错误自动在行动中插入pip install命令。Level 3: LLM引导修复对于上述方法无法解决的复杂错误如逻辑错误、语义错误才进入完整的结构化反馈循环。Level 4: 人工干预回退当循环超过一定次数或检测到危险操作如rm -rf时停止循环并通知人类。这种分层设计能有效降低延迟和成本同时保障系统安全。4.4 评估修复循环的有效性如何衡量你的结构化反馈循环是否有效需要定义一些评估指标任务最终成功率最直接的指标。平均修复尝试次数MTTR成功修复的任务平均需要几次循环。这个数字越低说明修复效率越高。修复路径合理性通过人工审查reasoning字段判断LLM的推理是否符合逻辑。泛化能力在训练集已知错误上表现良好后在未见过的错误类型上测试其表现。建立一个包含各种典型错误场景的测试集是迭代优化整个系统的关键。5. 常见陷阱与实战排坑指南在实际部署中我踩过不少坑这里分享几个最典型的案例和解决方案。5.1 幻觉导致的修复发散问题LLM在生成修复动作时有时会“幻觉”出一些不存在的错误原因并基于此进行修改导致问题越来越复杂。例如代码本是因缩进错误失败LLM却诊断是某个不存在的函数用法错误并开始重写大量无关代码。排查仔细检查修复协调器输出中的reasoning字段。如果发现其推理前提与事实不符如“代码中使用了process_data()函数”但实际并没有就是幻觉。解决强化上下文约束在提示词中明确强调“必须严格依据诊断报告中的‘错误位置’和‘可能的原因’进行分析”。引入验证步骤在应用修复前增加一个简单的验证。例如让另一个轻量级LLM或规则系统判断修复动作是否直接针对了反馈中的核心错误。设置编辑距离限制对于代码修复限制每次修改的代码行数或字符数。如果修复动作试图修改的代码范围远大于错误定位点则触发警告或回退。5.2 循环震荡与原地打转问题Agent在两个或多个错误的修复方案间来回切换无法收敛。例如第一次尝试安装包A失败第二次尝试卸载包A安装包B失败第三次又装回包A。排查查看完整的行动历史。如果发现状态如安装/卸载或参数在几个固定值间周期性变化就是循环震荡。解决增加循环记忆在提示词中不仅提供上一次的反馈而是提供最近2-3次的所有尝试和反馈历史明确告诉LLM“之前我们已经尝试过方案A和B均告失败请避免重复。”引入随机性当检测到可能震荡时如连续两次修复动作互为逆操作在提示词中加入“请尝试一个与之前所有方法都不同的新思路”或者让温度参数temperature暂时调高鼓励探索。定义失败模式如果同一个错误在3次循环后仍未解决强制跳出循环将问题升级如标记为“需人工处理”。5.3 结构化引擎的解析错误问题反馈结构化引擎本身解析错误导致传递给修复协调器的信息是错的。比如把“权限拒绝”错误解析成了“文件不存在”。排查对比结构化引擎输出的primary_error和raw_output_snippet看提取是否准确。这是系统中最需要日志监控的部分。解决实施降级策略当规则和轻量级LLM都无法高置信度解析时不要强行输出一个可能错误的结构化反馈。可以降级为将原始错误的关键部分直接高亮后传递给修复协调器并附加说明“解析失败请直接分析以下原始错误”。建立解析测试集收集历史上各种错误输出的样本定期运行结构化引擎进行测试确保其准确率。人工反馈闭环对于解析失败的案例可以设计一个简单界面让人工打标签正确的错误类型、原因是什么将这些数据用于微调一个小模型专门做错误分类。5.4 成本与延迟失控问题每个修复循环都调用大模型复杂任务可能循环多次导致总Token消耗和响应时间激增。排查监控每个任务的API调用次数、总Token数和总耗时。解决缓存常见修复方案对于“ModuleNotFoundError: requests”这种高频错误其修复动作pip install requests是确定的。可以建立一个缓存键是错误类型核心错误信息值是修复动作。命中缓存后直接执行无需调用LLM。使用阶梯式模型修复协调器不一定非要用最强大最贵的模型。可以用小模型如gpt-3.5-turbo处理大部分简单修复仅当小模型多次失败后再换用大模型如gpt-4进行“专家会诊”。设置硬性限制除了循环次数限制还应设置单次任务的总Token预算或最大耗时预算。超出预算即终止避免陷入无限循环或产生天价账单。构建一个健壮的结构化反馈修复循环更像是在训练一个具备“元认知”能力的数字员工。它不仅仅是在执行任务更是在学习如何从失败中学习。这个过程没有一劳永逸的银弹需要开发者持续地观察、调试和优化各个组件之间的交互。从我自己的实践来看投入精力设计好这个循环比单纯追求更强大的基础LLM往往能带来更直接、更可控的性能提升。尤其是在那些错误模式相对有限的垂直应用场景里一个精心设计的结构化反馈机制完全可以将Agent的任务成功率提升一个数量级。
