Agent工具调用错误处理实战：Harness兜底机制与10个真实场景解析

做 agent 开发这几年，我最大的感受是：工具调用（function calling / tool calling）这一环，决定了你的 agent 是“能干活”还是“像个玩具”。模型本身再聪明，只要工具调用链路上有一处出错，整个流程就会直接崩掉。而真正决定体验的，往往不是模型有多强，而是外围那层 harness 到底做了多少兜底。

这半年我把 DeepSeek、Codex，还有几套开源 agent harness 都拉出来实测了一遍，专门盯着“出错”这个环节看：参数传错、工具名幻觉、返回格式炸了、超时、死循环……一共整理了 10 个真实场景。这篇文章不聊空泛理论，就把每个场景的现场还原、出错原因、兜底结果和修改建议摊开讲。看完你至少能少踩一半的坑。

适合看的人：正在做 agent 应用的开发者、想给 LLM 应用接工具调用的同学、对 harness 和 agent 之间关系还拎不清的人。不管你是刚入门还是已经踩过坑，这篇都能给你一些可落地的参考。

1. 先对齐概念：Harness 到底是什么，它凭什么替模型兜底

1.1 一句话区分 Agent 和 Harness

先把概念说清楚，不然下面全白聊。Agent 是一个“会做事的程序”，它由大模型提供推理能力，通过工具调用去改状态、查数据、发请求。Harness 则是跑这个 agent 的“运行框架”，它管着模型的输入输出、工具注册表、调用流程、错误处理、上下文管理这些事。

打个比方：Agent 是司机，Harness 是车。司机负责看路、判断、打方向盘；车负责把指令变成轮胎的动作，并且在轮胎打滑、刹车失灵、油量不足的时候给出警告和补救。没有 harness 的 agent 也能跑，但一遇到异常就直接翻车。

现在很多人把“工具调用”和“agent”混着说，实际上工具调用是 agent 和外部世界之间唯一的信息通道。Harness 的核心工作之一，就是保证这条通道在出错时不会导致整个 agent 瘫痪。

从大家最近在搜“deepseek harness”“codex harness”“agent harness 可以发起工具调用，而不是自己就是工具”这些词就能看出来，越来越多人开始意识到：模型的输出只是一段文字，真正去执行、校验、纠错的是 harness。这个认知一旦到位，很多设计决策就顺了。

1.2 工具调用链路上的四个“事故高发区”

完整走一遍工具调用流程，大概是这样的：

1. 模型根据用户问题和已有的工具列表，决定调用哪个工具，输出一段结构化指令。
2. Harness 解析这段指令，拆出工具名和参数。
3. Harness 在注册表里找到对应工具，做参数校验。
4. 校验通过，真实执行工具，拿到返回结果。
5. Harness 把工具结果拼回对话上下文，重新交给模型继续推理。

这五个环节里，最容易出事的集中在第 1 到第 3 步和第 5 步。我总结成四个高发区：

• 幻觉区：模型编造了不存在的工具名、不存在的参数，或者把参数嵌套结构搞错。
• 解析区：模型输出的 arguments 不是合法 JSON，或者因为转义问题解析失败。
• 执行区：工具真实执行时报错、超时、返回了不符合约定的数据。
• 上下文区：工具结果太大，把上下文窗口撑爆，或者反复的错误信息把模型“带偏”。

这四个区域对应了 10 个场景里的大部分问题。下面逐个看现场。

1.3 兜底这件事，为什么不能指望模型自己

有一个很普遍的误区：觉得“模型这么聪明，给个错误提示它下次就会了”。实测下来并非如此。模型在同一个会话里面对同类错误，往往第一次错了，第二次还会用同样的方式错，尤其是参数嵌套和转义问题，反复出现的概率极高。

“工具调用嵌套 arguments 的问题反复”就是最典型的例子。模型不是不会改正，而是它的“改正”是基于概率的。同一个错误指令，模型重新生成的分布并没有多大变化。所以兜底必须靠 harness 用确定性逻辑来做，而不是寄希望于模型的下一次输出。

但是，模型也不是完全不参与兜底。正确的分工是：harness 负责拦截、解析、格式化、重试；模型负责在收到错误信息后重新规划。这就是后面要讲的“错误回填”机制。两者配合，才能形成一个真正的闭环。

2. 十场景实测：错误现场、兜底结果与修复动作

2.1 场景 01-02：参数侧的错误，最常见也最好修

场景 01：必填参数缺失。我让模型调用一个get_weather(city: string, date?: string)工具，模型只传了{"city": "北京"}，把date漏了。有的模型还会直接输出{}，等于什么都没传。这种场景在真实项目里出现频率最高。

现场还原时，我故意不提供任何默认值，harness 的 JSON Schema 校验直接拦截，错误信息回填给模型：

{ "status": "validation_error", "tool": "get_weather", "message": "Missing required field: date. Available fields: city (string), date (string, optional)." }

关键点在于，harness 没有真正发起外部调用，这是第一层兜底最重要的作用——把错误挡在调用之前。否则天气接口会返回 400，甚至最坏的情况是接口把date当成空值处理，返回一个“看似成功但实际错误”的结果，那才是最难排查的。

场景 02：参数类型错误。模型把send_email的to字段传成了数字12345，而不是字符串。这种错误在强类型语言环境里会直接抛异常，在弱类型环境里更危险——字符串拼接时可能不报错，但收件人地址已经错了。

我实测下来的兜底方案是：harness 做两层校验，先按 JSON Schema 做类型检查，再对关键字段做业务规则校验（比如 email 格式）。校验失败时，把“期望类型 + 实际类型 + 修复建议”一并回填给模型。实测发现，只要错误信息写得足够明确，模型第二次修正的成功率在九成以上。

2.2 场景 03-04：工具名幻觉与嵌套 arguments 问题

场景 03：工具名幻觉。这是我在 deepseek harness 上遇到最多次的问题。模型明明只注册了query_stock_price，它却输出get_stock_price。原因多半是模型在预训练阶段见过类似的函数名，输出时被“带跑”了。

兜底逻辑很简单：harness 在注册表里找不到对应工具时，不做任何调用，直接返回：

{ "status": "tool_not_found", "message": "Tool 'get_stock_price' does not exist. Available tools: query_stock_price, get_news, send_alert." }

注意这里要把可用工具列表原样返回，不是只告诉“不存在”。实测下来，把工具列表带进错误信息，模型重新选择工具的成功率能提升很多，因为它不需要再从上下文里翻找。

场景 04：嵌套 arguments 反复出错。这个场景是热词里明确提到的痛点。典型表现是模型需要把一个 JSON 字符串作为参数值，结果它输出的 arguments 变成了多层嵌套：

{ "name": "run_query", "arguments": "{\"payload\": \"{\\\"table\\\": \\\"users\\\", \\\"where\\\": \\\"id=1\\\"}\"}" }

这种转义地狱很容易解析失败。我在多套 harness 上都复现了这个问题，而且同一个模型会在连续几次调用中反复出现。兜底方案不能只做一次JSON.parse，我最后用的是逐步降级解析：先尝试标准解析，失败后尝试去掉转义斜杠再解析，再不行就提取最外层花括号手动修复。如果三次解析全部失败，才把原始字符串原样回填给模型，并明确提示“arguments 无法解析为合法 JSON，请重新输出不带转义的参数”。

2.3 场景 05-06：超时与非法返回，外部依赖的不可控

场景 05：工具调用超时。外部 API 不稳定是常态。我测过调用一个第三方股票接口，有时候 200ms 返回，有时候 30 秒都没响应。如果 harness 不设置超时，agent 会一直卡在这一步。

这里我的做法是用asyncio.wait_for包住工具执行，超时时间按工具类型区分：查询类给 10 秒，写入类给 30 秒。超时后返回给模型的错误信息会带上“操作已取消”的提示。有一点很重要：超时并不代表操作没发生。对方服务可能已经执行了写操作，只是响应丢失了。所以我在错误回填时会提醒模型“该操作状态未知，请先查询确认，再决定是否重试”，避免重复扣费或重复下单。

场景 06：工具返回非法 JSON。我测过一个内部日志工具，正常情况返回 JSON，但偶尔会在 stdout 里混入非 JSON 的日志行。harness 解析失败后如果直接抛错，模型就会懵掉。我的兜底方案是：尝试解析失败时，把原始文本包进一个结构化的返回里给模型：

{ "status": "unparsed_result", "tool": "read_log", "raw": "[INFO] connection pool created\n{...}" }

同时在status里明确标记 “unparsed_result”，模型看到这个标记就知道原始结果不完整，会主动要求重试或换一种方式读取。这个设计比直接把原始文本硬塞给模型要可靠得多。

2.4 场景 07-08：并发冲突和工具自身异常

场景 07：多工具并发冲突。现代 harness 基本都支持并行调用多个工具。模型一次输出三个工具调用请求：一个write_file，一个create_file，一个read_file，前面两个指向同一路径。如果 harness 无脑并发执行，就会出现竞态条件：写入的内容可能被覆盖，或者 create_file 发现文件已存在直接报错。

实测环境里，我在 harness 里引入了“工具依赖分析”：对同资源的写操作做串行化，对读写混合操作做顺序调整。具体规则是：同一资源，读操作可以并发，写操作必须互斥，写操作后的读操作必须等待。这条规则修掉了大量偶发问题。

场景 08：工具自身抛出异常。这个场景最能看出 harness 的成熟度。一个查询数据库的工具，因为连接池耗尽抛了ConnectionError。如果 harness 直接让整个 agent 崩溃，那设计就太粗糙了。正确做法是：harness 捕获异常，把异常类型、错误信息和上下文栈整理成一条消息回填给模型，让模型决定是换一个工具，还是调整参数重试，还是告诉用户“当前数据库不可用”。

我实测过给模型回填完整堆栈和只回填精简错误信息的区别。堆栈太长反而干扰模型判断，精简成“工具名 + 异常类型 + 一句人类可读描述”的效果最好。这是一个很值得记住的细节。

2.5 场景 09-10：上下文爆炸与重试死循环

场景 09：上下文被工具结果撑爆。有一个工具返回了一份 8 万 token 的 JSON 数据，直接导致整个会话上下文溢出。很多 harness 的默认行为是把所有工具结果原封不动塞进上下文，这是个大坑。

我的做法是给工具结果设置上限（比如单次最大 8000 token），超出的部分做智能截断：优先保留结果的摘要、错误信息和关键字段，丢弃冗余数据。如果工具本身支持分页，还会自动追加一次分页查询调用。实测下来，这个机制能把上下文占用缩小三分之二，同时不损失关键信息。

场景 10：重试死循环。这是最考验 harness 设计的地方。模型反复用同一个错误参数调用同一个工具，每次失败都重新生成一遍几乎相同的调用，最高纪录我看它连试了 8 次。这种死循环不仅浪费 token，还可能对外部系统造成重复操作。

兜底方案是加“连续错误计数”。当同一个工具连续失败超过 3 次，harness 就不再自动重试，而是切换到升级策略：要么给模型注入一份“当前可用工具 + 已失败原因 + 建议的替代方案”，要么直接中断流程请求人工接管。实测中，“建议的替代方案”比单纯报错有效得多，比如“数据库连接失败，建议改用缓存查询工具”，模型会顺着这个建议走。

3. 兜底机制逐层拆解：从报错到恢复，四层防线

3.1 第一层：结构化校验，把错误挡在调用之前

第一层防线是在工具真正执行之前做的校验。核心是两个部分：JSON Schema 校验和业务规则校验。

JSON Schema 校验解决的是“参数结构对不对”的问题：字段是否存在、类型是否正确、必填项是否齐全、枚举值是否在允许范围内。业务规则校验解决的是“参数值合不合理”的问题：日期不能是过去、金额不能为负、邮箱格式要合法。很多团队只做前者，结果参数结构都对，但值本身是错的，照样会在下游炸掉。

校验失败时，harness 返回的错误信息里要包含三样东西：失败原因、期望值、可用的替代方案。不要只报“参数错误”，那等于没报。我见过最差的一种实现是直接抛一个 Python 的ValidationError堆栈给模型，模型根本看不懂，只能瞎猜重试。

3.2 第二层：错误回填，让模型自己纠正自己

第二层防线是把结构化的错误信息回填进对话上下文，让模型基于错误信息重新规划。这一层的关键在于“给模型留一条活路”。

我常用的回填模板分三种情况：

• 参数问题：告诉模型具体哪个字段错了、期望什么格式，让它重新生成参数。
• 工具不存在：把完整的可用工具列表放进去，让它重新选择。
• 执行失败：给出精简的错误描述和可能原因，让它决定换工具、改参数还是放弃。

回填的位置也有讲究。放在本轮工具结果的位置，而不是追加到历史消息里，这样模型能清楚地知道“这是刚才那次调用的反馈”。如果错误信息混在历史对话里，模型很可能找不到对应关系，又重试一遍。

3.3 第三层：重试、退避与熔断，控制外部依赖的雪崩

第三层防线针对的是外部依赖的不确定性。重试不是简单“再调一次”，而是要有策略：

• 指数退避：第一次失败等 1 秒，第二次等 2 秒，第三次等 4 秒，防止给下游接口造成压力。
• 最大重试次数：一般控制在 2-3 次，超过就不要再试了。
• 熔断：如果同一个工具在短时间内连续失败（比如 5 分钟内 5 次），直接进入熔断状态，后续请求不再调用该工具，而是立即返回“当前工具不可用”。

熔断是很多自建 harness 容易漏掉的一环。没有熔断的话，外部服务一旦挂掉，你的 agent 就会疯狂重试，把错误放大成雪崩。加了熔断之后，问题就被限制在一个工具内部，不会影响整个 agent 的可用性。

3.4 第四层：状态恢复与人工接管，最后的防线

最后一层防线是保证整个会话状态的一致性和可控性。工具调用在执行过程中，可能会改外部系统的状态（发了邮件、建了文件、扣了款），如果后面流程出错，这些状态不会自动回滚。

所以 harness 里要有一个“操作记录”：每次工具调用的入参、出参、执行结果、失败原因都记录下来。这样一旦流程中断，开发者可以快速定位“到底哪一步已经发生了”，并手动处理补偿操作。

人工接管则是把控制权交还给人的机制。当连续错误超过阈值、或者模型多次无法完成用户请求时，harness 应该主动停止自动流程，把当前状态和已执行的操作汇总成报告，交给人工处理。这不是“认输”，而是把风险控制在可控范围内的专业做法。

4. 把兜底机制落地：配置清单、排查表和踩坑心得

4.1 我建议的兜底配置清单（可直接抄）

这半年我在自己维护的 harness 工程里，逐渐沉淀了一份配置清单。不涉及具体框架，直接照着设计即可：

• 工具注册表：每个工具声明 name、description、parameters（JSON Schema）、timeout、retry_policy、max_result_tokens。
• 全局校验器：在工具执行前统一走 JSON Schema 校验 + 业务规则校验。
• 错误信息模板：按“参数错误 / 工具不存在 / 执行失败 / 解析失败”四类定义回填格式，统一包含建议动作。
• 重试策略：默认最多重试 2 次，指数退避，超时按工具类型区分。
• 熔断配置：连续失败 5 次进入 5 分钟熔断。
• 结果截断器：每个工具结果最多保留 8000 token，超出部分自动摘要。
• 连续错误计数：同一工具连续失败 3 次，触发升级策略。
• 操作日志：每次工具调用都记录完整入参、出参、耗时、结果状态。

这份清单不需要一次全上，但每一条都能在某个场景里救你一次。就算你的项目还只是原型阶段，也建议先把校验和错误回填这两条加上，收益最大。

4.2 常见问题排查速查表

我整理了这次实测中命中率最高的几类问题，做成速查表，方便你排查时对照：

这张表不是万能的，但能覆盖我实测中八成以上的问题。你在自己的项目里遇到类似现象时，可以按这个顺序排查：先看工具名和参数对不对，再看返回数据能不能解析，最后看上下文和重试策略有没有问题。

4.3 几个反直觉的经验

最后分享几个实测中得来的反直觉经验，这些在文档里基本找不到。

第一，错误信息越“啰嗦”越容易让模型改正。我之前以为给模型精简的错误提示更好，比如只报“参数错误”，结果模型反复重试。改成“缺少字段 date，期望类型是 string，可选，格式为 YYYY-MM-DD”之后，修正率明显提升。模型的纠错能力依赖信息的完整度，这一点在多个模型上都有验证。

第二，不要迷信“让模型自己决定要不要重试”。模型对重试的态度非常不稳定，有时候失败了 5 次还在重试，有时候一次失败就放弃。重试逻辑应该由 harness 用确定性规则控制，模型只负责“怎么改”而不是“要不要再试”。

第三，工具调用的结构化输出不一定可靠。有些模型在强制 JSON 输出时会丢字段、加注释、甚至把整个 JSON 包在 markdown 代码块里。harness 的解析器要能处理这些情况，尤其是“代码块包裹”这种，我实测中遇到的概率不低。解析器里加一层“从代码块中提取 JSON”的逻辑，能省不少事。

第四，兜底逻辑别写死在业务代码里。工具函数本身要尽量保持纯净，只管自己的业务逻辑，校验、重试、熔断这些全都放到 harness 层做。这样换工具、加工具都更方便，而且兜底逻辑可以统一复用，不用每个工具各写一套。

5. 写在最后：兜底不是防御，是 agent 的基本功

这次把 10 个场景跑完，我最深的体会是：很多人做 agent，把注意力全放在“选哪个模型”“prompt 怎么写”上，却忽略了 harness 这层兜底架构。其实对于一个真正要上线跑业务的 agent，工具调用出错时能不能优雅恢复，远比模型单次推理的聪明程度重要。

我现在做 agent 项目的习惯是，先把错误处理流程画出来，再写业务逻辑。哪里校验、哪里重试、哪里熔断、哪里人工接管，这些提前定好，后面开发会省很多事。你也别期待一次就把兜底做到位，我这份配置清单也是踩了无数坑才慢慢沉淀出来的。遇到新问题，先记录现场，再补一层防线，比一次性追求完美可靠得多。

最后再分享一个小技巧：每次跑完一轮实测，把“模型犯的错”和“harness 接住的错”分开记。前者是模型能力问题，后者是你的架构问题。记几轮之后你会发现，大部分让你半夜起来修 bug 的，都是后者。把精力放在后者上，你的 agent 会越用越稳。