Agent 工程笔记①:工具调用失败时,先查哪三层

Agent 靠工具调用(tool calling)读写文件、跑命令、查接口。失败时,控制台往往只丢一句「tool error」,排障却可能停在错误层。

本系列叫「Agent 工程笔记」。第一篇只建立排查顺序:先分清失败发生在哪一层,再决定改提示、改 schema,还是改环境。

一、先说一个具体麻烦

你让 Agent「更新依赖并跑测试」。它调了终端工具,返回非零退出码。你以为是模型笨,把提示加长三倍,还是失败。

后来发现:命令在沙箱里根本没有 pnpm。问题在执行环境,不在「想不想得清楚」。

工具失败常见混在一起。分层以后,动作才对得上病。

二、三层分别是什么

第一层:模型决策

模型有没有选对工具?参数意图对不对?该不该在缺信息时先搜索再写?

症状:调错工具、漏调、乱调、该停不停。

第二层:协议与参数

工具名、JSON 参数、必填字段、类型是否符合 schema?MCP / API 是否校验失败?

症状:参数缺失、类型错误、未知工具名、解析失败。

第三层:执行环境

权限、网络、路径、依赖、超时、沙箱策略、密钥是否可用?

症状:命令找不到、权限拒绝、连不上、超时、磁盘只读。

三、推荐排查顺序

(A)先看原始工具结果:退出码、stderr、HTTP 状态,不要只看模型转述

(B)确认工具名与参数是否合法(第二层)

(C)在同一环境手动复现命令(第三层)

(D)若环境与参数都对,再回头看提示与决策(第一层)

很多人颠倒:先改人格化提示,却不复现命令。

四、每层最小修复动作

第一层:补约束与验收;减少工具数量;要求「先只读探测」。

第二层:收紧 JSON Schema;给枚举;对失败返回可机读错误码。

第三层:装依赖、开放路径、延长超时、提供只读凭据、修好沙箱。

下面是一个更利于第二层排查的工具错误返回示意。

json 复制代码
{
  "ok": false,
  "code": "ENOENT",
  "tool": "run_terminal",
  "message": "pnpm: command not found"
}

上面代码中,code 与 message 让宿主和模型都能定位到环境层,而不是笼统的「失败了」。

五、和 MCP / 约束验收的关系

MCP 把工具接到宿主;接上不等于稳。Server 挂了、schema 漂移、权限过宽,都会在二三层爆雷。

「约束 + 验收」主要稳住第一层:少让模型在模糊目标下乱点工具。三层要一起看。

六、常见误区

(1)只骂模型

多数是环境与契约。

(2)吞掉 stderr

等于丢掉第三层证据。

(3)工具说明过长却缺必填示例

第二层更容易出错。

(4)一次给二十个高危工具

第一层选错概率上升。

七、小结与下一篇

工具失败,先问:决策错了、参数错了,还是环境执行错了?按层动手,比反复加形容词有效。

下一篇预告:上下文太长时,砍什么、留什么。

(完)

相关推荐
隔窗听雨眠14 小时前
SQL执行计划固化的原理与稳定性工程
数据库·sql优化·执行计划
TDengine (老段)16 小时前
TDengine IDMP 功能点—数据接入
大数据·数据库·物联网·时序数据库·tdengine·涛思数据
索西引擎16 小时前
MySQL 进阶:视图、存储过程、存储函数与触发器
数据库·mysql
bksczm18 小时前
InnoDB 通用表空间与临时表空间详解
大数据·数据库·mysql
靠沿18 小时前
MySQL数据库进阶——存储过程和触发器
java·数据库·mysql
如夏倾城18 小时前
VRRP(虚拟路由器冗余协议Virtual Router Redundancy Protocol)
网络·python·网络协议·安全·智能路由器·负载均衡·信息与通信
小七在进步19 小时前
string的实现(1)
c++·笔记·visual studio
码少女19 小时前
MySQL--库与表的增删改查基础
java·数据库·mysql
Eyfcom19 小时前
〖物流 SaaS 实战 02〗SaaS 租户的计费与订阅模型:从“一锤子买卖”到“按需订阅”
linux·服务器·数据库·快递系统·物流saas实战
打工的小王20 小时前
postgresql和mysql对比
数据库·mysql·postgresql