agent-inspect
TypeScript AI Agent 本地调试工具：执行树可视化 + 回归测试 + 隐私安全分享
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
TypeScript AI Agent 本地调试工具：执行树可视化 + 回归测试 + 隐私安全分享
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
场景切入： 凌晨两点，你的 AI Agent 应用突然开始返回错误结果。你知道它调用了哪些工具、问了哪些 LLM，但这些调用分散在上千行控制台日志里，工具 A 的参数传给了工具 B，B 的返回值又流向了 C——一个完整的执行链路被切割成碎片，你不得不在日志里来回跳读，试图拼凑真相。这不是 bug，这是 Agent 调试的根本困境：执行链路对人类不可见。
agent-inspect 正是为解决这一困境而生。它将 TypeScript AI Agent 的执行过程从黑盒变成白盒，把每一次 LLM 调用、工具选择、工具执行、结果返回，分支决策全部记录下来，以**执行树（Execution Tree）**的形式呈现，让你一眼看清 Agent「在想什么、做了什么、为什么这么做」。
图1：快速上手——从安装到首次捕获执行树，只需5分钟
传统的 AI 应用（LLM API 调用）调试相对简单：发一个 prompt，收一个 response，日志清晰可见。但 Agent 不一样——它有自主决策能力：根据 LLM 返回选择下一步调用哪个工具，根据工具执行结果决定是否重试，根据中间状态决定分支走向。这种动态、多步、非确定性的执行模式，使得传统的单轮日志记录完全失效。
市面上的解决方案（LangSmith、Honeyhive、Braintrust 等）本质上是云服务：将追踪数据上传到第三方平台，好处是开箱即用，坏处是数据主权问题——医疗、金融、法律场景下，prompt 和输出可能包含敏感信息，上传到外部平台存在合规风险。
agent-inspect 正是从这个痛点出发，选择了一条完全不同的路线：本地优先，数据不上云，让开发者在自己的机器上就能完整复盘 Agent 的每一次思考与行动。
这是最基础的使用场景。当你怀疑某个 Agent 行为异常时：
observe() 包装 Agent 实例npx agent-inspect view <run-id> 在终端查看执行树，或 npx agent-inspect report 生成完整报告执行树会清晰展示：哪一步调用了哪个工具、传入的参数是什么、工具返回了什么、LLM 基于这些信息做了什么决策。如果中间出错，执行树会高亮显示第一个因果失败点，而不是简单抛出一个堆栈错误。
图2：执行树（Execution Tree）——清晰展示 Agent 的完整思考链路与决策路径
对于生产环境的 Agent 应用，最怕的是「AI 模型升级后行为变了」。新版 GPT-4o 比旧版更倾向于选择某个工具，Agent 行为因此产生了微妙的偏移——用户可能不会立即发现，但服务质量在悄悄下降。
agent-inspect 提供了 TraceContract 机制：为一个已验证正确的 Agent 运行「打标」，生成确定性契约，之后每次代码变更或模型升级后，运行相同的输入，比对契约是否仍然满足。这相当于给 Agent 加上了「CI 门禁」，不符合契约的变更在部署前就被拦截。
图3：TUI 终端界面——本地查看执行统计与质量指标
当需要将 Agent 运行记录分享给同事或客户时，原始记录可能包含敏感信息（内部 API key、用户数据、业务逻辑细节）。agent-inspect 提供了**敏感信息脱敏（Redaction）**工作流：
npx agent-inspect bundle 生成脱敏后的离线包npx agent-inspect verify-safe 验证脱敏完整性整个过程不经过任何第三方云服务，数据始终留在本地或你自己的服务器上。
agent-inspect 采用了 monorepo 结构（pnpm workspace），当前版本 6.7.2 共包含 20 个 npm 子包：
| 子包 | 用途 |
|---|---|
@agent-inspect/core | 核心引擎：observe 包装器、执行树构建、JSONL 写入 |
@agent-inspect/cli | 命令行工具：list / view / report / check / bundle 等 |
@agent-inspect/tui | 终端 UI（TUI）查看器 |
@agent-inspect/viewer | 通用查看器抽象 |
@agent-inspect/ai-sdk | Vercel AI SDK 适配器（generateText / streamText） |
@agent-inspect/openai-agents | OpenAI Agents JS 适配器 |
@agent-inspect/langchain | LangChain 回调适配器 |
@agent-inspect/harness | Fixture runner：真实项目回归测试 |
@agent-inspect/eval | 评估框架 |
@agent-inspect/circuit | 熔断器（防止 Agent 进入死循环） |
@agent-inspect/guardrails | 输入输出守卫（安全过滤） |
@agent-inspect/redact | 敏感信息脱敏 |
@agent-inspect/mcp-server | MCP（Model Context Protocol）只读服务器 |
@agent-inspect/studio | 自托管 Web 审查界面（Beta） |
@agent-inspect/vitest | Vitest 集成（测试报告） |
@agent-inspect/jest | Jest 集成（测试报告） |
@agent-inspect/vscode | VS Code 扩展 |
这种架构的优势在于按需使用：如果只需要核心调试能力，只需安装 agent-inspect 主包；如果需要对接特定框架（如 Vercel AI SDK），再按需添加对应适配器包，避免引入不必要的依赖。
图4：时间线视图——按时间维度展示 Agent 执行过程，直观定位性能瓶颈
安装方式简单到一行命令：
npm install agent-inspect
npx agent-inspect init --yes
node examples/agent-inspect-demo.mjs
npx agent-inspect list --dir .agent-inspect
官方提供了 5 个无 API key 的 starter 示例（examples/starters/），覆盖：基础调试、错误处理、多 Agent 协作、环境门控等常见场景。拿下来就能跑，跑完就能理解原理。
CLI 操作直观：list 查看记录列表、view 终端查看执行树、report 生成 Markdown 报告、check 运行回归测试、bundle 打包脱敏分享。无需学习复杂配置，上手即用。
局限一：仅限 TypeScript/Node.js。 agent-inspect 是 TypeScript 项目，面向 Node.js 生态。Python 开发者（LangChain、AutoGen 等）暂时无法使用，这是最大的生态局限性。
局限二：数据脱敏是 Best-Effort，不是 Certified。 作者明确指出 redction 是「尽力而为」而非「认证级别」，脱敏后仍需人工审查再分享。这个边界说得很清楚，但部分用户可能会误以为「用了 redact 就安全了」。
局限三：需要代码侵入。 要使用 agent-inspect，必须在代码中加入 observe() 包装器。对于已有大型代码库的项目，接入成本不可忽视。官方提供的适配器（AI SDK、OpenAI Agents、LangChain）降低了这一成本，但非适配器框架的接入仍需要手动改写。
随着 AI Agent 从实验走向生产，可观测性（Observability） 成为刚性需求。以 LangSmith、Helicone、Braintrust 为代表的云服务已经在这个赛道建立优势，但它们的共同问题是：数据必须上云。
agent-inspect 的出现代表了一种相反的哲学：本地优先，隐私优先。在数据合规要求日益严格的背景下（GDPR、医疗 PHI、金融数据），这个定位极具战略价值。虽然当前仍是单开发者维护的项目（rajudandigam），stars 增速相对平稳（218★），但其技术选型和路线清晰，填补了 TypeScript 生态本地 Agent 可观测性工具的空白。
对于 AI 应用开发者，agent-inspect 值得一试——尤其是当你在处理敏感数据、需要一个快速响应的本地调试工具、或者希望在 CI 中加入 Agent 回归测试时。