AgentInspect 本地轨迹调试工具

这个 Agent 能做什么，适合哪些场景？

AgentInspect 是面向 TypeScript AI Agent 的本地优先工具包，将运行记录保存为 JSONL，并提供 CLI、可导入的读取与检查 API，以及框架适配器。它可把嵌套步骤、工具调用、LLM 调用、耗时和错误展示为执行树与报告，帮助定位因果故障。通过轨迹预设、TraceContract 或测试套件，可以对已记录的运行执行确定性检查，并让 CI 根据结果退出。它还能生成经过脱敏处理的 Evidence v2 文件及清单，并离线校验文件哈希。核心调试、检查和证据流程无需 AgentInspect 账号或默认上传；需要 Node.js 20 或更高版本。

安装 agent-inspect 后，可用 init 写入示例，再运行示例生成本地 trace；用 list 查找运行记录，view、report 和 explain 检查执行路径。CLI 的 check 命令可用 --preset trajectory、--required-tool 等规则验证运行；程序也可通过 openTraceFile 读取 JSONL，并以 defineTraceContract 和 evaluateTraceContractRead 评估契约。对于分享，可运行 verify-safe 检查风险提示，再用 bundle 生成 Evidence v2，并用 bundle verify 离线复核清单中的哈希。可选适配器支持 LangChain/LangGraph、AI SDK 和 OpenAI Agents JS；Vitest、Jest 报告器以及预览阶段的 MCP 服务也可按需安装。

1. TypeScript Agent 开发者在本地复现一次工具调用失败，并通过执行树定位首个因果错误。
2. 维护 Agent 工作流的工程团队在 CI 中检查必需工具、步骤顺序或运行完成状态。
3. 使用 LangGraph、AI SDK 或 OpenAI Agents JS 的团队为现有框架运行接入对应适配器并查看 trace。
4. 需要将运行证据附到 PR、事故记录或支持请求的工程师，先脱敏生成离线可校验的 Evidence v2。
5. 已有结构化日志或 OpenInference/OTLP JSON 的团队通过 logs 或 open 命令将其纳入本地检查流程。

如何安装或部署这个 Agent？

需要 Node.js >=20。安装核心 CLI：

npm install agent-inspect

生成本地示例并运行：

npx agent-inspect init --yes
node examples/agent-inspect-demo.mjs
npx agent-inspect list --dir .agent-inspect

核心流程不要求账号或 API 密钥。集成框架时，按需安装 README 列出的适配器包，例如 @agent-inspect/langchain 或 @agent-inspect/openai-agents。

如何使用这个 Agent？

从 list 输出中复制 run ID，查看摘要并执行轨迹检查：

npx agent-inspect view <run-id> --dir .agent-inspect --summary
npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectory

生成并核验可分享的离线证据：

npx agent-inspect verify-safe <run-id> --dir .agent-inspect
npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share --out ./evidence
npx agent-inspect bundle verify ./evidence

程序化检查可读取 JSONL，并评估 TraceContract：

import { openTraceFile } from "agent-inspect/readers";
import {
  defineTraceContract,
  evaluateTraceContractRead,
} from "agent-inspect/checks";

const read = await openTraceFile("./trace.jsonl");
const contract = defineTraceContract({
  run: { requireCompleted: true },
  tools: { required: ["retrieve_policy"] },
});

const result = evaluateTraceContractRead(read, contract);
if (result.status !== "pass") process.exitCode = 1;

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

常见问题