浏览器自动化Agent死循环+Pydantic报错？实战修复指南

你的浏览器自动化 Agent 是否陷入了无限循环，同时不断抛出 Pydantic 验证错误？这不是个例。在 Reddit 上，一位开发者就遇到了这个令人抓狂的问题：Agent 卡在循环里，Pydantic 错误刷屏，调试无从下手。本文将从错误根源出发，给出系统性的排查和修复方案。

Reddit 用户求助截图

为什么 Agent 会陷入死循环？

浏览器自动化 Agent 的循环通常不是代码里写了个 while True，而是决策逻辑和状态反馈之间形成了闭环。常见诱因有三类：

状态判断失效。Agent 依赖页面元素或 URL 来判断当前步骤，如果选择器匹配不到、页面加载不完整，Agent 会认为“还没完成”，于是重试。重试逻辑如果没有次数上限，就会变成死循环。

LLM 输出的动作不可执行。当模型输出的动作（比如点击某个不存在的按钮）被拒绝后，Agent 可能把错误信息重新喂回模型，模型再次输出同样的动作，形成自我强化的循环。

异常处理缺失。Pydantic 验证失败时，如果外层没有捕获并终止流程，而是简单重试，就会在同一个错误上反复撞墙。

Pydantic 报错说明了什么？

Pydantic 错误本质上不是“循环的原因”，而是“循环的症状”。它告诉你：Agent 收到的数据结构不符合预期。

典型的报错场景包括：LLM 返回的 JSON 缺少必填字段、字段类型不匹配（比如期望 int 却收到字符串）、或者嵌套模型的结构对不上。当 Agent 把工具调用参数直接交给 Pydantic 模型验证时，任何格式偏差都会触发 ValidationError。

关键在于：Pydantic 验证失败后，你的代码做了什么？ 如果只是捕获异常然后重试，而没有修正输入或改变策略，循环就会持续。

Pydantic 是 Python 生态中广泛使用的数据验证库，其核心是 BaseModel 类：开发者通过类型注解声明字段结构，Pydantic 在实例化时自动校验数据类型、必填性与嵌套关系。当输入不符合模型定义时，它会抛出 ValidationError，其中包含每个出错字段的 loc（位置路径）、type（错误类型，如 missing、int_parsing）和 msg（人类可读描述）。在 LLM 应用场景中，Pydantic 常被用作“结构化输出”的守门员——模型返回的 JSON 先经过模型验证，再交给下游工具执行。因此，报错本身是保护机制在起作用，而非缺陷；真正需要关注的是错误被触发后的处理策略。

系统性修复步骤

1. 给循环加上硬性终止条件

无论重试逻辑写在哪里，都要设置最大迭代次数。一个实用的做法是在 Agent 主循环中维护步数计数器，超过阈值（比如 10 步或 20 步）就强制退出，并输出当前状态快照。这不能解决根本问题，但能防止调试时无限刷屏，也能让错误日志保留下来。

2. 让 Pydantic 错误可读且可行动

Pydantic 的原始错误信息对 LLM 并不友好。建议在捕获 ValidationError 后，提取结构化的错误详情（字段名、错误类型、期望值），转换成自然语言提示，再决定是重新请求模型还是终止流程。同时，在模型定义中使用 Field(description=...) 为每个字段添加说明，能显著降低模型输出格式错误的概率。

3. 引入状态去重与循环检测

记录每一步的动作和页面状态哈希。如果连续几步的动作和状态组合重复出现，就判定为循环，主动中断并输出诊断信息。这比单纯限制步数更精准，也能帮你定位是哪一步的反馈出了问题。

状态哈希通常指对当前页面关键特征做摘要计算，常见做法包括：对 DOM 中目标区域做规范化序列化后取哈希、对 URL 与页面标题组合取哈希，或对可交互元素列表排序后拼接再哈希。哈希的好处是能把“看起来相同”的状态归一化，避免因时间戳、随机 ID 等噪声导致误判。循环检测则在此基础上维护一个滑动窗口，比较最近 N 步的 (动作, 状态哈希) 二元组；若窗口内重复率超过阈值，即判定进入循环。该机制与最大步数限制互补：步数限制是兜底，状态去重能更早发现“在原地打转”的模式。

4. 检查工具调用的参数校验层

Pydantic 错误往往出现在工具调用边界。确认你的 Agent 框架（无论是 LangChain、LlamaIndex 还是自研）在把 LLM 输出传给工具前，是否做了宽松解析。可以考虑使用 model_validate_json 配合容错模式，或者在模型定义中为可选字段设置默认值，避免因为一个字段缺失就整体失败。

5. 加入人工断点与可观测性

在开发阶段，为 Agent 的每一步输出结构化日志：当前步骤、模型原始输出、解析结果、验证状态。这样当循环发生时，你能快速看到是从哪一步开始偏离预期。没有可观测性，调试 Agent 的循环问题几乎等于盲人摸象。

预防胜于修复

这类问题的根源在于 Agent 的“容错设计”缺失。一个健壮的浏览器自动化 Agent 应该具备：明确的终止条件、对模型输出的宽容解析、对验证错误的分类处理，以及可回放的状态日志。把这些当成基础设施来建设，比每次出问题再救火要划算得多。