算
Agent 调工具本身成功了,但返回结果解析失败,整个流程卡住,这种故障在落地时特别常见。我把遇到的解析失败分成三类,排查思路各不相同。
一、格式不规范:模型输出不是合法 JSON
最常见的是多余的解释文字、Markdown 代码块标记、尾随逗号。解决办法是把 schema 约束写进工具描述,明确要求“只输出 JSON,不要解释”。实测下来,约束写得越具体,格式合规率越高。兜底可以在解析前做一层清洗:提取第一个 { 到最后一个 } 之间的内容再解析。
二、输出被截断:字段缺了一半
长结果容易在 max_tokens 处被拦腰截断。排查时先看日志里的原始输出是不是以不完整的字段结尾。如果是截断,优先让工具返回精简字段,或者把大结果拆成多次调用返回。只调大 max_tokens 是治标不治本。
三、字段漂移:结构对了,字段名或类型变了
模型偶尔会把 user_id 写成 userId,或者把数字写成字符串。我的做法是在解析层做宽容处理:字段名做别名映射,类型做强制转换,转换失败再走重试。关键字段缺失时直接触发一次带纠错提示的重试,而不是让流程静默失败。
四、监控和复现
解析失败一定要把原始输出完整记下来,只记错误码没法复现。建议对解析失败做采样留存,定期看一眼失败分布,格式类问题和截断类问题的优化方向完全不同。
你们在 Agent 落地时解析失败率大概是多少?主要卡在格式、截断还是字段漂移上?欢迎分享实测数据。
一、格式不规范:模型输出不是合法 JSON
最常见的是多余的解释文字、Markdown 代码块标记、尾随逗号。解决办法是把 schema 约束写进工具描述,明确要求“只输出 JSON,不要解释”。实测下来,约束写得越具体,格式合规率越高。兜底可以在解析前做一层清洗:提取第一个 { 到最后一个 } 之间的内容再解析。
二、输出被截断:字段缺了一半
长结果容易在 max_tokens 处被拦腰截断。排查时先看日志里的原始输出是不是以不完整的字段结尾。如果是截断,优先让工具返回精简字段,或者把大结果拆成多次调用返回。只调大 max_tokens 是治标不治本。
三、字段漂移:结构对了,字段名或类型变了
模型偶尔会把 user_id 写成 userId,或者把数字写成字符串。我的做法是在解析层做宽容处理:字段名做别名映射,类型做强制转换,转换失败再走重试。关键字段缺失时直接触发一次带纠错提示的重试,而不是让流程静默失败。
四、监控和复现
解析失败一定要把原始输出完整记下来,只记错误码没法复现。建议对解析失败做采样留存,定期看一眼失败分布,格式类问题和截断类问题的优化方向完全不同。
你们在 Agent 落地时解析失败率大概是多少?主要卡在格式、截断还是字段漂移上?欢迎分享实测数据。