论
Member
智能体落地的最后一公里,往往不在模型能力,而在工具调用失败时的处理。模型选错工具、参数格式不对、工具本身报错、网络超时、返回结果解析失败,这些情况在演示里很少出现,在生产环境里天天发生。工具调用的失败处理没做好,智能体给用户的体验就是“时灵时不灵”。
先把失败分个类,处理方式完全不同:
第一类,参数格式错。模型生成的参数缺字段、类型不对、枚举值不在允许范围。这类失败不应该重试,重试多少次都一样错。正确做法是把工具返回的错误信息原样喂回模型,让模型修正参数再调一次,同时记录下来:哪个工具、哪个参数最容易错,是提示词没写清楚还是工具描述本身有歧义。
第二类,工具本身报错。数据库连不上、下游 API 返回 500、文件不存在。这类失败要看是不是暂时的:超时和限流可以重试,权限错误和数据不存在重试也没用。重试要有策略:指数退避加抖动,重试上限一般两到三次,超过就转降级或人工。
第三类,超时。工具执行时间超过预期,原因可能是下游慢、也可能是任务本身就重。超时之后最麻烦的是“不知道到底执行了没有”:重试可能导致重复执行,不重试可能任务根本没做。这就引出了幂等的问题。
幂等是工具设计的第一原则。写操作类的工具(下单、发消息、改数据)要带幂等键:同一个幂等键重复调用,只执行一次、返回第一次的结果。读操作天然可重试,不用担心重复。设计工具的时候就要想清楚:这个工具被重复调用两次会发生什么?如果答案是“会重复下单”或“会重复扣款”,那这个工具就不应该直接暴露给智能体。
人工接管是最后一道防线,要事先定好触发条件:连续失败超过设定次数、单次任务耗时超过阈值、工具返回了需要人判断的错误。接管时要把上下文打包给人:已经做了哪些步骤、工具返回的原始错误是什么、模型当时的推理是什么。只给人一句“出错了”等于没接管,人还要从头排查一遍。
降级路径也要提前想好。查订单失败了,能不能先返回缓存的订单摘要?发消息失败了,能不能先记下来稍后重试?降级不是“糊弄用户”,是明确告诉用户“这一步暂时做不了、已经记录下来、预计什么时候恢复”。
最后是可观测性。每一次工具调用都要记录:工具名、输入参数摘要、返回结果摘要、耗时、成功还是失败。没有这些记录,线上出问题只能靠猜。记录时注意脱敏,密码、Token、用户隐私数据不要进日志。
你们在智能体项目里,工具调用失败率最高的是哪类问题?重试策略和人工接管是怎么设计的?欢迎分享实战经验。
先把失败分个类,处理方式完全不同:
第一类,参数格式错。模型生成的参数缺字段、类型不对、枚举值不在允许范围。这类失败不应该重试,重试多少次都一样错。正确做法是把工具返回的错误信息原样喂回模型,让模型修正参数再调一次,同时记录下来:哪个工具、哪个参数最容易错,是提示词没写清楚还是工具描述本身有歧义。
第二类,工具本身报错。数据库连不上、下游 API 返回 500、文件不存在。这类失败要看是不是暂时的:超时和限流可以重试,权限错误和数据不存在重试也没用。重试要有策略:指数退避加抖动,重试上限一般两到三次,超过就转降级或人工。
第三类,超时。工具执行时间超过预期,原因可能是下游慢、也可能是任务本身就重。超时之后最麻烦的是“不知道到底执行了没有”:重试可能导致重复执行,不重试可能任务根本没做。这就引出了幂等的问题。
幂等是工具设计的第一原则。写操作类的工具(下单、发消息、改数据)要带幂等键:同一个幂等键重复调用,只执行一次、返回第一次的结果。读操作天然可重试,不用担心重复。设计工具的时候就要想清楚:这个工具被重复调用两次会发生什么?如果答案是“会重复下单”或“会重复扣款”,那这个工具就不应该直接暴露给智能体。
人工接管是最后一道防线,要事先定好触发条件:连续失败超过设定次数、单次任务耗时超过阈值、工具返回了需要人判断的错误。接管时要把上下文打包给人:已经做了哪些步骤、工具返回的原始错误是什么、模型当时的推理是什么。只给人一句“出错了”等于没接管,人还要从头排查一遍。
降级路径也要提前想好。查订单失败了,能不能先返回缓存的订单摘要?发消息失败了,能不能先记下来稍后重试?降级不是“糊弄用户”,是明确告诉用户“这一步暂时做不了、已经记录下来、预计什么时候恢复”。
最后是可观测性。每一次工具调用都要记录:工具名、输入参数摘要、返回结果摘要、耗时、成功还是失败。没有这些记录,线上出问题只能靠猜。记录时注意脱敏,密码、Token、用户隐私数据不要进日志。
你们在智能体项目里,工具调用失败率最高的是哪类问题?重试策略和人工接管是怎么设计的?欢迎分享实战经验。

