授权与合规声明本文为技术实践笔记示例均基于公开文档与自建环境中的实验不涉及任何未获授权的系统。文中结论仅代表个人实践小结与所涉厂商无利益关系。转载请注明出处。1. 为什么工具调用是 Agent 最脆的一环很多人搭 Agent 的第一感觉是模型选得好工具接上就能跑。但真正上线后才发现最容易出问题的不是模型推理而是工具调用Function Calling这一跳模型决定调哪个工具、填什么参数然后你把参数喂给真实系统执行。这一跳把语言模型的不确定性直接连到了外部系统的确定性后果。模型偶尔说胡话只是丢脸工具调错一次可能就改了数据库、发了消息、扣了钱。所以工具调用不能只做调得通必须做调错了也能兜住。本文不重复讲怎么定义工具 schema只讲五类最常踩的失败模式以及每类怎么兜底。2. 失败模式一参数幻觉与 schema 不匹配模型在填参数时最常见的两类毛病第一类编造不存在的取值。比如工具要求status只能是active/paused/closed模型却填了个pending理由是听起来合理。这种问题在枚举型字段上尤其频繁。第二类把函数调用参数当成了自由文本。模型本应传入结构化 JSON却塞进一段自然语言或者把数字写成带单位的字符串传30天而不是30。解析端一报错整轮对话就断了。兜底思路不是信任模型而是在调用真实系统前加一层校验# 示意调用前做 schema 校验不合法直接打回重填frompydanticimportBaseModel,ValidationErrorclassQueryArgs(BaseModel):status:strlimit:intdefsafe_call(args:dict):try:qQueryArgs(**args)exceptValidationErrorase:# 把错误回灌给模型让它自己改参数而不是抛异常中断return{retry:True,error:e.errors()}returndo_real_query(q)⚠️ 上面是结构示意字段按你的真实工具定义替换未在本机实测。关键点是校验失败不要直接报错终止而是把错误信息回灌给模型让它重试。多数情况下模型第二次就能填对。3. 失败模式二长耗时工具超时与半完成状态有些工具本身快但有些跑一个 SQL、生成一份报告、调一个第三方接口可能要好几秒甚至更久。模型默认是同步等结果一旦超过超时阈值你拿到的不是结果而是半截状态。更麻烦的是半完成工具已经对外部系统产生了副作用比如已经写了一半文件、已经发起了转账请求但调用方因为超时被中断你既不知道成功没成功也无法安全重试——重试可能重复生效。两个工程上的处理原则把查询类和写入类工具分开对待。查询可以放心重试写入必须带幂等键idempotency key让下游能识别这是同一次操作别重复执行。给模型明确的状态回报。超时时不要返回空而是返回操作已发起状态待确认让模型进入等待/轮询分支而不是盲目继续。这套失败模式怎么系统梳理我把五类模式的识别信号和兜底代码骨架整理成了笔记放在资料包里扫码即可获取4. 失败模式三工具返回不可信与解析失败模型调用工具后拿到的是工具返回的文本或 JSON。这里有两个坑坑一返回结构漂移。同一个工具今天返回{ ok: true, data: ... }明天上游改了返回{ success: ... }。模型按旧结构解读直接误判。坑二把工具返回当事实照单全收。工具本身可能出错返回了空数据、返回了异常堆栈、返回了查无结果却没被识别。模型不二次校验就直接编进答案于是用户看到的是一段自信的胡说。兜底做法对工具返回做最小必要校验至少判断三类——是否成功、关键字段是否齐全、内容是否为错误信号异常栈、超时提示。只有通过校验的返回才进入下一轮推理不通过就走重试 / 换工具 / 如实告知用户分支。5. 失败模式四权限越界与副作用不可控这是最危险的一类。模型在对话里自主决定调用某个有副作用的工具但这次调用超出了用户实际授权范围。典型场景用户只是问帮我看看上个月的账单模型顺手调了导出全部用户数据或者用户说稍微改一下配置模型调了重启服务。工程上必须在工具层而不是模型层做权限隔离每个工具标注危险等级高危工具写入、删除、对外发送默认需要二次确认或人工审批。工具的可见范围按角色收敛不让模型在对话上下文里看到它这轮不该用的工具。所有副作用操作留审计日志出了问题能回溯是哪一轮、哪个意图触发。权限隔离具体怎么落地我把工具分级 审批网关 审计的接入样例整理在了一起放在资料包里扫码即可获取6. 失败模式五多工具编排中的上下文污染当 Agent 串起多个工具上下文会越长越杂。问题不在长而在上一工具的中间结果污染了下一工具的输入判断。比如工具 A 返回了一大段原始日志模型没做摘要就把它整段塞进下一轮导致工具 B 把日志里的某行误当成用户指令去执行。或者多轮重试把错误上下文反复叠加模型越跑越偏。两个缓解手段工具返回先摘要再入上下文。长返回不要原样进历史先压缩成关键结论 必要字段。每轮明确当前意图把工具结果严格绑定到意图上不让模型自由地把任意历史片段当作新指令。7. 一个可落地的兜底设计清单把上面五类归纳成一份上线前 checklist每一条都能单独验证所有工具参数先 schema 校验再执行校验失败回灌模型重试不中断链路写入类工具强制幂等键查询类才允许自由重试工具返回做最小必要校验成功态 / 关键字段 / 错误信号不过滤就进推理高危工具分级 二次确认 / 审批按角色收敛可见范围所有副作用留审计日志可回溯触发意图长返回先摘要再入上下文每轮绑定当前意图做到这六条工具调用从调得通变成调错了也兜得住。Agent 的稳定性往往就差在这一层兜底上。附表 A本文引用事实与出处对照表事实出处本文位置工具调用把模型不确定性连接到外部系统确定性后果需做调用前校验本文工程经验结论无一手出处待验证第 1、2 章写入类操作应引入幂等键避免重复执行分布式系统领域共识本文不引用具体文献第 3 章工具返回需校验成功态与关键字段避免模型照单全收本文工程经验结论无一手出处待验证第 4 章高危副作用工具应做权限分级与审计安全工程通用实践本文不引用具体文献第 5 章长上下文下工具返回应摘要后再入上下文防止污染本文工程经验结论无一手出处待验证第 6 章附表 B术语速查表术语含义Function Calling让模型以结构化参数调用外部函数的能力工具 schema描述工具名称、参数、类型的结构化定义幂等键标识一次操作的唯一键重复提交不产生重复副作用副作用调用对外部系统产生的变更写入、发送、删除等上下文污染不相关的历史内容干扰了后续推理或工具调用审计日志记录谁、在何时、因何意图触发了什么操作的日志写在最后这篇用到的资料写这篇的时候我把团队 Agent 上线后踩过的工具调用坑重新归了类顺手也整理了几份配套的东西工具调用兜底 checklist上面六条的工程化版本可直接照着接参数校验与重试骨架基于 schema 校验、失败回灌模型的参考实现高危工具分级与审批样例权限隔离的最小可用方案资料是我自己整理的放在下面这个码上扫码即可获取资料较多建议先看「全套 AGI 大模型学习路线」再挑一个实战项目跟练。