agent-inspect - 在本地看清 TypeScript AI agent 的执行树

AI agent 的调试难点，不是“有没有日志”，而是日志经常太平。一个真实 agent run 里可能有计划步骤、工具调用、LLM 调用、重试、分支、并行任务和失败恢复。它们在 console 里通常只是连续的行，想还原因果关系，需要人脑自己把时间线拼回树。

今天推荐的 rajudandigam/agent-inspect 做的是这件事：把 TypeScript / Node.js agent 的本地运行过程记录成 execution tree，再用 CLI 查看、汇总、比较或导出。

发布时 GitHub 页面显示项目约 35 stars、20 forks，主要语言是 TypeScript。GitHub 搜索结果记录仓库创建于 2026-05-02，最近更新时间为 2026-06-07。包元数据和 package.json 均显示当前版本为 1.1.0，许可是 MIT，Node 要求是 >=20。

项目概览

属性	详情
仓库	rajudandigam/agent-inspect
定位	TypeScript AI agent 的本地执行树调试器
Stars	约 35
Forks	20
主要语言	TypeScript
许可	MIT
当前 npm 版本	1.1.0

它解决的是 inner loop 的可观察性

很多团队已经有生产环境 observability：日志平台、trace collector、dashboard、告警。但 agent 开发的内循环常常更朴素：本地跑一个 eval、改一段 prompt、换一个工具调用顺序、再跑一次。

在这个阶段，把所有内容接入完整生产观测系统未必划算。你需要的是一个能快速回答这些问题的小工具：

• 这次 run 到底走了哪些步骤？
• 哪个 tool call 最慢？
• 失败发生在哪个嵌套步骤里？
• 改了 prompt 之后，执行路径有没有变化？
• 能不能把 trace 导出成 Markdown 放进 PR 或复盘里？

agent-inspect 的 README 明确把它定位为本地优先工具。默认不需要账号，不上传云端，也不要求 dashboard。它更像是 agent 开发者手边的 trace 放大镜，而不是生产观测平台的替代品。

基本用法很轻

安装方式就是普通 npm 包：

npm install agent-inspect

代码里可以用 inspectRun 包住一次 agent 运行，再用 step、step.tool、step.llm 标记不同层级：

import { inspectRun, step } from "agent-inspect";

await inspectRun(
  "support-agent",
  async () => {
    const plan = await step("plan", async () => {
      return { intent: "refund-policy" };
    });

    const policy = await step.tool("retrieve-policy", async () => {
      return { text: "Refunds are available within 30 days." };
    });

    return step.llm("generate-answer", async () => {
      return `${plan.intent}: ${policy.text}`;
    });
  },
  { traceDir: "./.agent-inspect" }
);

运行后再用 CLI 看结果：

npx agent-inspect list --dir ./.agent-inspect
npx agent-inspect view <run-id> --dir ./.agent-inspect
npx agent-inspect view <run-id> --dir ./.agent-inspect --summary

这个模型的好处是克制。你不用一开始就设计完整 trace schema，也不用改造整个服务。先把关键步骤包起来，就能得到一个本地 JSONL trace 和可读的树。

已有结构化日志也能接进去

有些项目已经有 pino、winston、log4js、NestJS logger 或自定义 JSONL 事件流。对这些项目来说，重新给所有函数包 step 可能不现实。

agent-inspect 的 logs 命令处理的是这条路径。它可以从已有日志里读取 run id、event、timestamp 等字段，把扁平日志组织成 timeline 或 tree：

npx agent-inspect logs ./agent.log \
  --format json \
  --run-id-key requestId \
  --event-key event \
  --timestamp-key timestamp

README 里也写得比较谨慎：JSON logs 是一等支持；log4js 风格文本行属于 best-effort；不会把 JavaScript object literal 当作日志交换格式去 eval。这类边界很重要，因为 agent trace 里经常会出现用户输入、工具输出和模型文本，日志解析不应该为了“智能”牺牲安全性。

1.1.0 的重点是可控打开和 trace 安全

CHANGELOG.md 里，1.1.0 的变化集中在几个实用点：

• 新增 maybeInspectRun()，可以用 AGENT_INSPECT 环境变量控制是否写 trace。
• inspectRun 增加 enabled 选项，方便在不需要时 passthrough。
• 默认对手写 trace metadata 做 redaction，并限制事件和 metadata 的大小。
• LangChain adapter 支持 opt-in 的 JSONL 持久化。
• 补充 pino、log4js、NestJS 等结构化日志 recipes。
• 修复 ESM / CommonJS TypeScript consumer 的条件类型导出兼容。

这些变化说明项目在补“真实团队会遇到的问题”。比如 eval harness 和 CI 里，不是每次都要写 trace。更合理的方式是默认关闭，需要调查某个失败样本时再用环境变量打开。再比如 trace 文件很容易不小心塞入敏感 metadata 或巨大 payload，默认 redaction 和 size bound 比事后提醒更有用。

CLI 命令覆盖了调试闭环

README 里的 CLI 命令覆盖了本地调试常见闭环：

• list：找到最近的 runs。
• view：把某次 run 看成 tree。
• clean：清理旧 trace 文件。
• logs：把已有结构化日志转成 tree / timeline。
• tail：运行时跟随日志。
• export：导出 Markdown、HTML、OpenInference-compatible JSON、OTLP JSON。
• diff：比较两次本地 run。

这里我最在意的是 diff 和 export。很多 agent 问题不是单次失败，而是“改动前后行为变了”。如果 prompt 或 routing 改完以后，run tree 从三步变成七步，或者某个 fallback 开始频繁触发，diff 会比单纯看最终答案更早暴露问题。

export 则适合协作。把本地 trace 导成 Markdown 放到 PR、issue 或内部复盘里，比截图和散乱日志更容易 review。README 也提醒，OpenInference / OTLP JSON 这类导出是兼容取向，不等于默认上传到某个后端。

可选 LangChain adapter 和 TUI

核心包之外，项目还提供可选组件：

• @agent-inspect/langchain：LangChain.js callback adapter，默认偏 metadata，persist: true 时才持久化。
• @agent-inspect/tui：基于终端的交互式 viewer，供 view --tui 这类场景使用。

这两个组件都适合作为增量采用路径。已有 LangChain.js 项目可以先接 callback；需要更交互式查看的人可以加 TUI。README 同时说明这些 programmatic surfaces 仍是 experimental 或可能独立演进，因此生产里应该把稳定依赖放在核心 API 和 CLI 上。

适合什么团队

我会优先推荐给三类场景：

1. 正在写 TypeScript / Node.js agent，并且现在主要靠 console log 调试。
2. 有 eval 或 CI 样本，希望失败时能保留本地 trace artifacts。
3. 已有结构化 JSON logs，但缺少把同一次 run 聚合成可读树的工具。

不太适合的场景也清楚：如果你需要的是生产级 dashboard、跨服务分布式 tracing、成本分析、回放系统或供应商托管平台，agent-inspect 不是那个产品。它的价值在于小、近、本地、可放进开发循环。

小结

rajudandigam/agent-inspect 值得关注，是因为它没有把 AI agent 调试变成又一个重平台。它先把最基本的因果结构补回来：一次 run 里，哪些步骤发生了，谁嵌套在谁里面，哪个工具慢了，哪个 LLM 调用失败了，前后两次路径差在哪里。

随着 agent 从 demo 走向真实产品，调试的单位会从“看最终回复”变成“看执行过程”。agent-inspect 提供的是这个转变里很实用的一块：本地 JSONL trace、终端树、日志导入、diff 和导出。对小团队来说，这可能正好够用。