1. 从"Agent 该不该学新东西"这个问题说起

做 Agent 开发的人，早晚会撞上一个很别扭的问题：你辛辛苦苦搭好的 Agent，跑起来之后表现还不错，但过了一段时间你会发现它开始"力不从心"——不是它坏了，而是它遇到的东西变了。新的 API 版本、新的报错模式、新的用户意图、新的工具调用组合，这些在它被构建的那一刻根本不存在。它不会自己意识到"我该补课了"，只会一遍遍用旧知识硬扛，然后失败。

这就是mini_agent这类轻量 Agent 项目里最容易被忽略、但迟早要面对的一环：Agent 的自我认知边界。换句话说，Agent 怎么知道自己该学点新东西了？

这个问题听起来很哲学，落到工程上其实非常具体。它涉及三个层面：第一，Agent 怎么判断当前任务超出了自己的能力范围；第二，判断出来之后，它怎么把"我搞不定"这件事转化成可执行的信号；第三，这个信号怎么驱动后续的知识补充或工具扩展。很多人做 Agent 只做了第一层的一半——加个 try/except 就完事了，结果 Agent 永远在同一个坑里反复摔。

我拿mini_agent这个项目名来展开，是因为"mini"这个词本身就暗示了一种设计取向：不追求大而全的框架，而是把 Agent 的核心循环做薄、做透。在这种薄架构里，"知道自己该学新东西"这件事反而更容易看清楚，因为没有那么多抽象层帮你把问题藏起来。

这篇文章适合两类人看：一类是正在用 Python 搭 AI Agent、已经跑通了基本 loop 但卡在"怎么让它持续进化"的开发者；另一类是刚开始接触 Agent 概念、想理解 Agent 和普通脚本本质区别的入门者。我会从判断机制、信号设计、知识落地三个角度拆开讲，中间穿插我在实际项目里踩过的坑和验证过的做法。

先说一个反直觉的结论：Agent 感知到自己"该学新东西"，靠的不是更聪明的模型，而是更诚实的失败记录。模型再强，如果没有一套机制把"失败"这件事结构化地记下来、分析出来，它永远不知道自己缺什么。这一点在后面会反复出现。

2. 能力边界的三种信号：Agent 怎么察觉"我不行了"

2.1 显式失败：最直接但也最容易被浪费的信号

最容易被 Agent 捕捉到的信号就是显式失败——工具调用返回错误、API 抛异常、解析结果为空、超时。这些在代码层面都是可捕获的。但问题在于，大多数mini_agent的实现里，这些失败信号被处理得太粗糙了。

我见过太多这样的代码：

try: result = tool.call(params) except Exception as e: return f"工具调用失败: {e}"

这段代码的问题不在于它捕获了异常，而在于它把异常"拍平"了。ConnectionError和KeyError和ValidationError被压成了同一个字符串，Agent 拿到这个字符串之后，除了重试或者放弃，做不了任何有意义的判断。它不知道自己缺的是网络稳定性、参数理解能力，还是对某个领域概念的无知。

正确的做法是给失败分类。我在自己的mini_agent里会把失败信号分成至少四类，每类对应不同的"学习需求"：

这个分类表本身就是 Agent 自我认知的基础。当 Agent 连续三次遇到"参数类失败"，它就应该意识到：不是这次运气不好，而是我对这个工具的理解有系统性缺口。这个"连续三次"的阈值不是拍脑袋定的，后面会讲怎么调。

2.2 隐性失败：结果看起来对，但其实是错的

比显式失败更麻烦的是隐性失败。工具调用没报错，返回了结果，Agent 也把结果用上了，但最终输出是错的。这种失败在mini_agent这种轻量架构里特别隐蔽，因为没有复杂的验证层帮你兜底。

举个我实际遇到的例子。我做过一个 Agent，任务是"根据用户描述查询合适的数据库配置"。它调用了一个配置推荐工具，工具返回了一个 JSON，Agent 解析后给出了建议。整个过程零报错。但用户反馈说建议的配置根本跑不起来。排查后发现：工具返回的 JSON 里有个字段叫max_connections，Agent 把它理解成了"最大连接数"，但实际上这个工具里它指的是"最大空闲连接数"。语义错位，但没有任何异常。

这种失败怎么让 Agent 自己察觉？靠的是结果验证回路。具体做法是：在 Agent 的输出环节加一个轻量的自检步骤，用另一个 prompt 或者一个规则引擎去问"这个结果和原始需求对得上吗"。对不上的时候，不是直接报错，而是生成一条"语义缺口"记录。

我在mini_agent里用的自检 prompt 大概长这样：

SELF_CHECK_PROMPT = """ 原始任务: {task} 执行结果: {result} 请判断: 执行结果是否完整、准确地满足了原始任务? 如果存在偏差，请指出偏差类型: - 字段语义偏差 - 范围偏差 - 格式偏差 - 逻辑偏差 只输出偏差类型和一句话说明，不要展开。 """

这个自检本身也会消耗 token，所以不能每步都做。我的经验是只在"任务链路的最后一个工具调用之后"做一次，成本可控，收益明显。

2.3 用户反馈：被低估的边界信号

用户说"不对"、"再试试"、"这不是我要的"，这些反馈在大多数 Agent 实现里只是被当成一次新的输入，重新走一遍 loop。但实际上，用户反馈是最高质量的"学习需求"信号，因为它直接标注了 Agent 的能力缺口。

问题在于，用户反馈往往是模糊的。"不对"这两个字背后可能是参数错了、可能是理解错了、可能是工具选错了。Agent 需要把模糊反馈转化成结构化信号。我的做法是在mini_agent里加一个反馈解析层，把用户反馈和上一轮的执行轨迹拼在一起，让模型判断"用户不满意的具体环节是哪个"。

这里有个实操心得：不要让模型直接判断"我哪里错了"，而是让它判断"用户最可能对哪一步不满意"。前者会让模型陷入自我评价的困境，后者是相对客观的归因任务，准确率高很多。我实测下来，归因准确率能从大概六成提到八成以上。

3. 把"我该学了"变成可执行信号：信号聚合与阈值设计

3.1 单次失败不值得学，连续模式才值得

Agent 察觉到自己该学新东西，关键不在于捕捉到一次失败，而在于识别出失败的模式。一次参数错误可能只是用户输入太奇怪，连续五次同类参数错误就说明 Agent 对这个工具的理解有系统性问题。

我在mini_agent里用一个简单的滑动窗口来做这件事。每个失败信号带一个failure_type标签，维护一个最近 N 次执行的失败队列，当某个类型的失败在窗口内出现次数超过阈值，就触发"学习需求"事件。

from collections import deque, Counter class FailureTracker: def __init__(self, window_size=20, threshold=3): self.window = deque(maxlen=window_size) self.threshold = threshold def record(self, failure_type: str): self.window.append(failure_type) counter = Counter(self.window) if counter[failure_type] >= self.threshold: return self._emit_learning_signal(failure_type, counter[failure_type]) return None def _emit_learning_signal(self, failure_type, count): return { "signal": "learning_needed", "type": failure_type, "evidence_count": count, "window_size": self.window.maxlen }

窗口大小和阈值怎么定？我的经验是：窗口 20、阈值 3 是个不错的起点。窗口太小会误报，太大则反应迟钝。阈值 3 的意思是"同类失败出现三次才认为是模式"，低于这个数大概率是噪声。如果你的 Agent 执行频率很高，可以把窗口放大到 50，阈值提到 5。

注意：阈值不要设成 1。我早期图省事设成 1，结果 Agent 动不动就触发"学习"，把大量噪声当成了信号，反而干扰了正常执行。

3.2 学习信号要带上下文，不能只有类型

光知道"参数类失败出现了三次"还不够，Agent 需要知道是哪个工具的参数失败、哪类参数、在什么任务场景下。没有上下文的信号，后续没法转化成具体的学习动作。

所以我在信号里会带上这些字段：

• tool_name：出问题的工具
• task_context：当时的任务类型或意图
• sample_inputs：最近几次失败的实际输入（脱敏后）
• error_messages：原始错误信息

这些字段合起来，才能让后续的"学习"有的放矢。比如信号告诉你"query_database工具在'配置推荐'任务下，连续三次因为max_connections字段语义理解错误而失败"，这就非常具体了，可以直接驱动一次针对性的知识补充。

3.3 信号分级：不是所有学习需求都同等紧急

我在实践里发现，把所有学习信号一视同仁会导致两个问题：要么 Agent 频繁打断正常流程去"学习"，要么重要信号被淹没在噪声里。所以信号需要分级。

我的分级标准是这样的：

P0 的判断标准是"这个工具失败后，当前任务没有任何替代路径可走"。这个判断需要 Agent 对任务依赖图有基本认知，在mini_agent里我通常用一个简单的工具依赖表来实现，不需要搞得太复杂。

4. 学习动作的落地：从信号到真正的能力补充

4.1 学习不等于重新训练，多数时候是知识注入

一提到 Agent"学新东西"，很多人第一反应是微调模型或者重新训练。这在mini_agent这种轻量项目里既不现实也没必要。绝大多数情况下，Agent 需要的"学习"是知识注入——把缺失的信息补进它的上下文或外部知识库。

具体来说，学习动作可以分成三类：

1. 工具知识补充：更新工具的 schema 描述、参数说明、使用示例
2. 领域知识补充：往 RAG 知识库里加文档，或者更新系统 prompt 里的领域规则
3. 策略知识补充：调整任务分解模板、重试策略、工具选择优先级

这三类里，第一类最容易自动化，第三类最需要人工介入。我的建议是先从第一类做起，跑通了再考虑后面两类。

4.2 工具知识补充的自动化路径

当学习信号指向"工具理解不足"时，最直接的补充方式是让 Agent 自己去读工具的文档或源码，然后生成更准确的工具描述。这个流程可以完全自动化：

def auto_enrich_tool_knowledge(tool_name, failure_samples): # 1. 拉取工具的原始文档或源码 raw_doc = fetch_tool_doc(tool_name) # 2. 让模型对比失败样本和原始文档，找出理解偏差 prompt = f""" 工具文档: {raw_doc} 失败样本: {failure_samples} 请分析: Agent 在使用这个工具时，对哪些参数或行为的理解存在偏差? 输出格式: 每个偏差一行，格式为"参数名: 正确理解 vs 常见误解" """ analysis = llm_call(prompt) # 3. 生成增强版的工具描述 enriched_desc = generate_enriched_description(raw_doc, analysis) # 4. 写回工具注册表 update_tool_registry(tool_name, enriched_desc)

这个流程我实测跑通过，效果不错。关键是第 2 步的 prompt 设计——要让模型做"对比分析"而不是"重新总结"，前者能精准定位偏差，后者容易丢失细节。

4.3 领域知识补充：RAG 的增量更新

如果学习信号指向领域知识缺失，那就需要往 RAG 知识库里加内容。这里有个坑：不要直接把失败样本塞进知识库。失败样本是"错误示范"，直接塞进去会污染检索结果。

正确的做法是：从失败样本里提取出"缺失的知识点"，然后针对性地补充正确的知识。比如 Agent 反复搞错某个业务概念，你应该补的是这个概念的正确定义，而不是"Agent 曾经搞错过它"这个事实。

我在mini_agent里用一个中间层来做这件事：失败样本先经过一个"知识点提取"步骤，产出结构化的知识缺口描述，再由人工或模型去填充正确内容，最后才写入知识库。这个中间层看起来多了一步，但能有效避免知识库被污染。

4.4 学习效果的验证：怎么知道学对了

学完之后必须验证，否则你不知道这次"学习"是真的补上了缺口，还是只是换了个方式继续错。验证方法很简单：用触发学习的那些失败样本重新跑一遍。

如果之前失败的任务现在能跑通，说明学习有效。如果还是失败，说明要么知识补充得不对，要么问题根本不在知识层面（可能是工具本身有 bug，或者任务定义有问题）。

我在mini_agent里维护了一个"回归测试集"，每次触发学习后自动把相关失败样本加进去，定期跑一遍。这个测试集不需要很大，几十条就够用，但能帮你快速判断学习动作的有效性。

提示：回归测试集要定期清理。有些失败样本随着工具升级或任务变化已经不再 relevant，留着只会增加噪声。我一般每个月清理一次，把连续多次通过的样本移出去。

5. 一个完整的判断-学习闭环示例

5.1 场景设定

假设你的mini_agent是一个"数据查询助手"，用户可以用自然语言让它查数据库、生成报表。它注册了几个工具：query_database、generate_chart、export_report。

5.2 失败累积过程

第一天，用户问"查一下上个月的销售总额"，Agent 调用query_database，参数里写了date_range: "last_month"，工具报错说日期格式不对。Agent 重试，改成2024-05-01到2024-05-31，成功。这是一次偶发失败，记录为 P2。

第二天，又有三个用户问了类似的时间范围查询，Agent 又犯了同样的错误。FailureTracker 的窗口里现在有四次param_format_error，类型都是date_range。阈值触发，生成 P1 学习信号。

第三天，一个用户问"查一下上个季度的数据"，Agent 再次因为时间格式失败，而且这次它重试了三次都没成功，任务完全阻塞。升级为 P0 信号。

5.3 学习动作执行

P0 信号触发后，Agent 暂停正常服务，执行学习流程：

1. 提取失败样本：所有涉及date_range的失败调用
2. 分析根因：Agent 不理解工具期望的日期格式，总是用自然语言表达
3. 补充知识：在query_database的工具描述里加一条明确说明——"date_range参数必须是YYYY-MM-DD格式的字符串，不接受自然语言表达。如果需要转换，先调用parse_date工具。"
4. 更新工具注册表
5. 用失败样本回归测试

5.4 闭环验证

回归测试跑完，之前失败的样本现在都能正确处理。Agent 恢复服务。同时，这个学习过程被记录到日志里，包括触发原因、学习动作、验证结果。下次遇到类似信号时，可以参考历史处理方式，避免重复劳动。

这个闭环看起来简单，但真正跑通需要把前面讲的信号分类、阈值判断、知识补充、回归验证都串起来。我在第一次实现的时候，光是把失败信号的上下文传对就花了不少时间——因为mini_agent的调用链比较薄，很多上下文在传递过程中容易丢。

6. 实操中容易踩的几个坑

6.1 把"学习"做成了"无限重试"

最常见的坑：Agent 检测到失败后，不是去补充知识，而是换个参数重试。重试几次都失败，就放弃了。这本质上没有学习，只是把失败延后了。

判断你的 Agent 是真学习还是假重试，看一个指标：同一个失败模式是否在后续任务中再次出现。如果出现了，说明学习没生效。我在mini_agent里专门加了一个"复发检测"，如果某个学习信号处理完之后，同类失败在接下来 50 次执行里又出现了，就标记为"学习失败"，需要人工介入。

6.2 学习信号被高频任务淹没

如果你的 Agent 执行频率很高，失败信号会快速填满窗口，导致阈值频繁触发。这时候需要做信号采样，不是每个失败都记录，而是按比例采样。我的做法是：P0 类失败全量记录，P1 类按 50% 采样，P2 类按 10% 采样。这样既能捕捉模式，又不会让窗口被噪声占满。

6.3 知识补充后没有失效机制

补充的知识会一直留在工具描述或知识库里，但有些知识会过时。比如工具升级后参数格式变了，你之前补充的说明就变成了错误信息。所以知识补充必须带有效期或版本号，定期review。

我在mini_agent里给每条补充知识加了一个last_verified时间戳，超过 30 天没有被验证过的知识会被标记为"待复核"，下次触发相关学习信号时优先检查这些知识是否还有效。

6.4 忽略了"学错了"的可能

有时候 Agent 触发了学习信号，补充了知识，但补充的知识本身是错的。这种情况在自动化流程里特别危险，因为错误会被固化下来。所以自动化学习流程必须有人工审核环节，至少对于 P0 级别的学习动作，不能完全放手让模型自己决定补什么。

我的做法是：P0 学习动作生成的知识补充方案，先进入待审核队列，人工确认后才写入。P1 和 P2 可以自动写入，但会记录来源，方便追溯。

7. 关于 mini_agent 这类轻量架构的一点个人体会

做mini_agent这种薄架构的 Agent，最大的好处是每个环节都看得见。你不需要去猜框架在背后做了什么，失败信号从哪来、怎么流转、最后变成什么动作，全在你自己写的代码里。这让"Agent 怎么知道自己该学新东西"这个问题变得可解——因为你可以把判断逻辑写得很直白。

但薄架构也有代价：所有机制都要自己搭。信号分类、阈值判断、知识补充、回归验证，这些在重型框架里可能有现成组件，在mini_agent里都得手写。我的建议是不要一上来就追求完整闭环，先把"失败分类"和"信号记录"这两件事做扎实，跑一段时间看看数据，再决定要不要加自动学习。很多时候你会发现，光是让 Agent 把失败原因记清楚，就已经解决了大半问题——因为你自己看日志的时候，一眼就能看出它缺什么。

最后分享一个我一直在用的小技巧：给 Agent 加一个"困惑度"指标。不是模型层面的困惑度，而是任务层面的——统计 Agent 在一次任务里调用工具的失败次数、重试次数、以及最终是否成功。这个指标持续偏高，就说明 Agent 在当前任务分布下能力不足，该考虑补充知识或调整策略了。这个指标比单看失败率更敏感，因为它捕捉的是"挣扎"的过程，而不只是"失败"的结果。