AgentInspect 让开发者能够将 AI Agent 的逐步操作捕获为 JSONL 日志，从而能够验证所需的工具是否已运行——而无需将 OpenTelemetry 集成到技术栈中。

在一个基于 Vercel AI SDK 构建的天气查询示例进行的快速测试中，AgentInspect 标记了一个“静默失败”：最终答案是正确的，但天气工具调用从未发生。该库的进程级检查捕捉到了普通输出测试会忽略的问题。

为什么执行路径至关重要

AI Agent 的响应是一个链条的最终产物，该链条可能包含多次模型调用和外部工具调用。如果一个提示词（prompt）本应获取实时数据，那么即使文本看起来正确，缺失该获取过程也会改变风险状况。仅针对答案层面的测试会让跳过关键步骤的 Bug 在不被察觉的情况下进入生产环境。

AgentInspect 的功能

  • 轻量级记录 – 一个 TypeScript 适配器挂钩到 Agent 代码中，并将每次模型调用、工具调用及其顺序写入行分隔的 JSON (JSONL) 文件。
  • 规则引擎 – 开发者可以声明简单的谓词，例如“必须调用天气工具”或“不得使用金融 API”。该库会在每次运行后评估这些规则。
  • CLI 检查 – 失败的运行会被保存为文件，内置的命令行工具可以打开这些文件，以人类可读的方式回放执行轨迹。

由于日志是本地文件，因此无需追踪后端、网络配置或单独的可观测性服务。

测试是如何设置的

  1. 进程检查 – 一条规则用于验证是否调用了天气工具端点。
  2. 答案检查 – 一个独立的断言将生成的文本与预期的室内观光建议进行比较。

运行了两种场景：

场景 答案检查 进程检查
正常路径（已获取天气） 通过 通过
跳过天气（工具从未调用） 通过 失败

第二次运行展示了进程检查的价值：答案看起来没问题，但缺失的工具调用预示着一个隐藏的缺陷。

AgentInspect 对比 Promptfoo

Promptfoo 是一个更成熟的测试框架，它通过 OpenTelemetry 捕获轨迹。这种方法对于已经将遥测数据发送到收集器的团队来说效果很好，但它增加了配置开销以及对追踪基础设施的依赖。

AgentInspect 的应用阶段更偏向开发早期，但它的设置非常简单。

谁应该关注

  • CI 流水线 – 增加一个运行 AgentInspect 的步骤，并在违反规则时使构建失败，可以将静默 Bug 转化为强制停止。
  • 调试 – JSONL 日志可以在本地打开，以回放确切的调用序列，与在远程追踪仪表板中挖掘相比，这节省了大量时间。
  • 产品团队 – 在发布功能之前，确认关键的数据获取确实已经发生，可以降低下游用户投诉的风险。

核心结论： 当 AI Agent 的正确性取决于它采取的行动，而不仅仅是最终文本时，像 AgentInspect 这样的轻量级记录器可以将隐藏的进程 Bug 转化为可见、可测试的失败——且无需承担完整追踪技术栈的开销。