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

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

AI Summary (BLUF)

MCP工具返回isError:true时,Promise仍可能正常完成,导致测试误报成功。本文用AgentInspect的合成测试展示如何区分协议完成、工具错误和实际结果,并建议在集成边界扩展测试。

核心洞察

这篇文章点破了一个很隐蔽的坑:await 成功返回,测试全绿,但工具其实报错了。作者把"调用返回了"、"工具报告失败"、"业务真的成功了"这三件事拆开讲,这个区分在写 agent 测试时特别容易忽略。我觉得最有价值的是那句"每个绿色结果都应该说明它到底验证了哪个边界",这话值得贴在显示器上。


一个 await 结束了。应用拿到了返回值。trace 里有一个已完成的工具 span。测试通过。

但工具同时返回了 isError: true。

这不矛盾。JavaScript 的 promise 完成和 MCP 工具成功是两种不同的信号。把它们当成同一个信号,会制造一种特别安静的失败:agent 在一个被拒绝的操作之后继续往下跑,而只检查完成状态的测试却报告成功。

我是 AgentInspect 的维护者。这篇文章用针对 agent-inspect@6.31.35 和 @agent-inspect/mcp@6.31.35 的合成测试来区分这些信号。不涉及模型调用,也不描述任何生产事故。

核心结论

  1. JavaScript 的 Promise 完成与 MCP 工具成功是两种独立信号:await 正常返回、trace 中工具 span 已完成、测试通过,但工具结果仍可能携带 isError: true,二者并不矛盾。

  2. 应用需要区分三层边界——调用是否返回(Promise 完成或协议响应)、工具是否报告失败(MCP 结果的 isError)、预期结果是否真正发生(独立观察到的状态或回执),这三者不能压缩成同一个"绿色通过"。

  3. 在 agent-inspect@6.31.35 与 @agent-inspect/mcp@6.31.35 的合成测试中,仅断言 requireCompleted: true 的契约检查返回 pass,而增加 observations: { failOn: ["failed"] } 后同一 trace 返回 fail,证明只测完成状态会漏掉工具层失败。

  4. wrapper 保留调用方原始返回值(恒等断言通过),同时为 MCP 工具错误记录一条失败的结果观察;追踪适配器只记录证据,恢复策略仍由应用决定。

  5. 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 截图。TraceContract 还是 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 工具返回 isError:true 时,测试还是显示成功?

因为 JavaScript 的 promise 完成和 MCP 工具成功是两种不同信号。await 正常返回只说明调用返回了,isError:true 表示工具报告失败,只检查完成状态的测试就会误报成功。

怎么在 agent 测试里区分协议完成、工具错误和实际结果?

用 TraceContract 分别断言:requireCompleted 只验证调用返回,加 observations.failOn:["failed"] 才能捕获工具错误。每个绿色结果都应说明它验证了哪个边界。

工具返回 isError 就应该自动重试吗?

不应该。isError 不是可重试性分类,参数错误、权限被拒原样重试只是增加工作量,有副作用的操作重试还可能造成重复效果。应使用应用掌控的有界策略。

阿凯广州
本文由 阿凯 审核,最后更新于 2026年11月17日
联系编辑 →
← 返回文章列表
分享到:微博

版权与免责声明:本文仅用于信息分享与交流,不构成任何形式的法律、投资、医疗或其他专业建议,也不构成对任何结果的承诺或保证。

文中提及的商标、品牌、Logo、产品名称及相关图片/素材,其权利归各自合法权利人所有。本站内容可能基于公开资料整理,亦可能使用 AI 辅助生成或润色;我们尽力确保准确与合规,但不保证完整性、时效性与适用性,请读者自行甄别并以官方信息为准。

若本文内容或素材涉嫌侵权、隐私不当或存在错误,请相关权利人/当事人联系本站,我们将及时核实并采取删除、修正或下架等处理措施。也请勿在评论或联系信息中提交身份证号、手机号、住址等个人敏感信息。