await 成功、测试全绿,工具却报错了:Agent 测试里最安静的失败

AI Summary (BLUF)
MCP工具返回isError:true时,Promise仍可能正常完成,导致测试误报成功。本文用AgentInspect的合成测试展示如何区分协议完成、工具错误和实际结果,并建议在集成边界扩展测试。
核心洞察
这篇文章点破了一个很隐蔽的坑:await 成功返回,测试全绿,但工具其实报错了。作者把"调用返回了"、"工具报告失败"、"业务真的成功了"这三件事拆开讲,这个区分在写 agent 测试时特别容易忽略。我觉得最有价值的是那句"每个绿色结果都应该说明它到底验证了哪个边界",这话值得贴在显示器上。
一个 await 结束了。应用拿到了返回值。trace 里有一个已完成的工具 span。测试通过。
但工具同时返回了 isError: true。
这不矛盾。JavaScript 的 promise 完成和 MCPModel Context Protocol - a protocol that enables AI models to access external tools, data sources, and services to enhance their capabilities and context awareness. 工具成功是两种不同的信号。把它们当成同一个信号,会制造一种特别安静的失败:agent 在一个被拒绝的操作之后继续往下跑,而只检查完成状态的测试却报告成功。
我是 AgentInspect一个用于检查和追踪AI代理运行的JavaScript库,提供MCP客户端包装和TraceContract检查功能。 的维护者。这篇文章用针对 agent-inspect@6.31.35 和 @agent-inspect/mcp@6.31.35 的合成测试来区分这些信号。不涉及模型调用,也不描述任何生产事故。
核心结论
JavaScript 的 Promise 完成与 MCP 工具成功是两种独立信号:
await正常返回、trace 中工具 span 已完成、测试通过,但工具结果仍可能携带isError: true,二者并不矛盾。应用需要区分三层边界——调用是否返回(Promise 完成或协议响应)、工具是否报告失败(MCP 结果的
isError)、预期结果是否真正发生(独立观察到的状态或回执),这三者不能压缩成同一个"绿色通过"。在
agent-inspect@6.31.35与@agent-inspect/mcp@6.31.35的合成测试中,仅断言requireCompleted: true的契约检查返回pass,而增加observations: { failOn: ["failed"] }后同一 trace 返回fail,证明只测完成状态会漏掉工具层失败。wrapper 保留调用方原始返回值(恒等断言通过),同时为 MCP 工具错误记录一条失败的结果观察;追踪适配器只记录证据,恢复策略仍由应用决定。
isError不等于可重试性分类:参数错误、权限被拒、资源不可用、临时故障都可能产生失败结果,对有副作用的操作在响应含糊时重试可能造成重复效果,应使用应用自身掌控的有界策略并区分只读恢复与写操作。
“成功”背后藏着的三个问题
MCP 工具规范区分了协议层错误和工具结果内部报告的错误。一个合法的结果可以携带 isError: true。
对应用来说,还有第三层边界:请求的效果到底有没有发生。
| 问题 | 证据 | 它不能证明什么 |
|---|---|---|
| 调用返回了吗? | Promise 完成或协议响应 | 工具接受了这个操作 |
| 工具报告失败了吗? | MCP 结果的 isError |
外部系统的最终状态 |
| 预期结果发生了吗? | 独立观察到的状态或回执 | 之前每一步执行都正确 |
一个预订工具可能正常响应,告诉你库存不足。一个邮件工具可能接收了消息,但没证明送达。一次数据库超时可能让写入结果变得不确定。
这些情况需要不同的应用行为。它们不该被压缩成一个绿色的勾。
返回的错误是需要评估的证据,不是自动重试的指令。
从一个刻意做小的复现开始
安装版本匹配的包:
npm install --save-exact agent-inspect@6.31.35 @agent-inspect/mcp@6.31.35
这个 JavaScript fixture 故意不是真实的 MCP 服务器。它隔离出 wrapper 的返回值分支:
import assert from "node:assert/strict";
import { mkdtemp, readdir } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { inspectRun } from "agent-inspect";
import { wrapMcpClient } from "@agent-inspect/mcp";
const traceDir = await mkdtemp(join(tmpdir(), "mcp-result-"));
const response = {
isError: true,
content: [{ type: "text", text: "Synthetic request rejected" }],
};
const client = wrapMcpClient(
{ async callTool() { return response; } },
{ serverName: "fixture" },
);
const returned = await inspectRun(
"returned-tool-error",
() => client.callTool({ name: "lookup_policy", arguments: {} }),
{ traceDir, silent: true },
);
assert.strictEqual(returned, response);
const [filename] = (await readdir(traceDir))
.filter(name => name.endsWith(".jsonl"));
那个恒等断言很关键。埋点不该悄悄把调用方的结果换成另一个对象,也不该凭空造一个异常。在这个版本里,wrapper 保留原结果,同时为这个 MCP 工具错误记录一条失败的结果观察。
响应仍然归应用管:解释拒绝、选择有授权的降级方案、请求澄清,或者直接停下。追踪适配器只记录证据,不替你选恢复策略。
测观察结果,别只测完成状态
把这段追加到同一个 fixture:
import { openTraceFile } from "agent-inspect/readers";
import {
defineTraceContract,
evaluateTraceContractRead,
} from "agent-inspect/checks";
const trace = await openTraceFile(join(traceDir, filename));
const completionOnly = evaluateTraceContractRead(
trace,
defineTraceContract({ run: { requireCompleted: true } }),
);
const withOutcomes = evaluateTraceContractRead(
trace,
defineTraceContract({
run: { requireCompleted: true },
observations: { failOn: ["failed"] },
}),
);
assert.equal(completionOnly.status, "pass");
assert.equal(withOutcomes.status, "fail");
这些是测试 harness 里实测出来的结果,不是手画的 CLI 截图。TraceContractAgentInspect中的一种契约定义,用于对追踪数据(如运行完成状态、观察结果)进行断言和验证。 还是 beta 接口,锁死版本,把 fixture 和契约放在一起。
注意第二个检查说了什么:一条被捕获的观察报告了失败。它没说 AgentInspect 独立查询了预订系统或验证了数据库事务。观察来自 MCP 响应。它的来源决定了它的证据强度。
别把每个工具错误都变成重试
isError 不是可重试性分类。
参数格式错误、权限被拒、资源不可用、临时依赖故障,都可能产生失败的工具结果。前两种原样重试只是增加工作量,不是恢复。对一个有副作用的操作,在响应含糊时重试可能造成重复效果。
优先用应用自己掌控的有界策略。把只读恢复和写操作分开。远端服务支持幂等的话,按那个服务真实的契约来。wrapper 和 trace 字段都不会让一个操作变成恰好一次。
也别把任意错误文本解析成策略决策。如果你的服务器暴露了经过审查的结构化错误分类,就测那些分类。如果没有,保留不确定性,别从“timeout”这个词去猜。
在集成边界上扩展 fixture
假客户端只证明了一个很窄的行为。采用 wrapper 之前,补上真实 SDK 测试:正常结果、抛出的错误、isError、取消、方法接收者、生命周期方法。用独立计数的服务器 handler 去核对捕获的调用。
配套示例里有一个用内存传输的已安装 MCP SDK 客户端/服务器测试。它覆盖了 SDK 方法兼容性,但不代表网络重连、认证或每种传输都测过了。
这个区分值得养成习惯:每个绿色结果都应该说明它到底验证了哪个边界。
如果你现在的 agent 测试只断言了 promise 被 resolve,加一个工具明确拒绝请求的 fixture。这次运行看起来还成功吗?如果是,缺的那个断言大概不在最后那句话上。
实现参考
- 审查提交里的 MCP wrapper 实现
- 带版本的 TraceContract 文档
- 配套示例:
examples/probes.test.mjs,测试D01。
常见问题(FAQ)
为什么 MCP 工具返回 isErrorMCP工具结果中的一个布尔字段,表示工具是否报告了错误,但协议本身仍可能正常返回该结果。:true 时,测试还是显示成功?
因为 JavaScript 的 promise 完成和 MCP 工具成功是两种不同信号。await 正常返回只说明调用返回了,isError:true 表示工具报告失败,只检查完成状态的测试就会误报成功。
怎么在 agent 测试里区分协议完成、工具错误和实际结果?
用 TraceContract 分别断言:requireCompleted 只验证调用返回,加 observations.failOn:["failed"] 才能捕获工具错误。每个绿色结果都应说明它验证了哪个边界。
工具返回 isError 就应该自动重试吗?
不应该。isError 不是可重试性分类,参数错误、权限被拒原样重试只是增加工作量,有副作用的操作重试还可能造成重复效果。应使用应用掌控的有界策略。
版权与免责声明:本文仅用于信息分享与交流,不构成任何形式的法律、投资、医疗或其他专业建议,也不构成对任何结果的承诺或保证。
文中提及的商标、品牌、Logo、产品名称及相关图片/素材,其权利归各自合法权利人所有。本站内容可能基于公开资料整理,亦可能使用 AI 辅助生成或润色;我们尽力确保准确与合规,但不保证完整性、时效性与适用性,请读者自行甄别并以官方信息为准。
若本文内容或素材涉嫌侵权、隐私不当或存在错误,请相关权利人/当事人联系本站,我们将及时核实并采取删除、修正或下架等处理措施。也请勿在评论或联系信息中提交身份证号、手机号、住址等个人敏感信息。




