agent-inspect - TypeScript AI agent の execution tree を local で読む

AI agent の debugging で難しいのは、log がないことではありません。Log が flat すぎることです。実際の agent run には planning step、tool call、LLM call、retry、branch、parallel task、failure recovery が含まれます。しかし console 上では、それらがただの連続した行になりがちです。因果関係を戻すには、人間が頭の中で timeline を tree に組み直す必要があります。

今日紹介する rajudandigam/agent-inspect は、この問題を扱う tool です。TypeScript / Node.js agent の local run を execution tree として記録し、CLI で表示、summary、comparison、export ができます。

公開時点の GitHub page では、およそ 35 stars、20 forks。主な言語は TypeScript です。GitHub search result では repository creation が 2026-05-02、recent update が 2026-06-07 と記録されていました。Package metadata と package.json では現在 version は 1.1.0、license は MIT、Node requirement は >=20 です。

プロジェクト概要

項目	内容
Repository	rajudandigam/agent-inspect
位置づけ	TypeScript AI agent の local execution-tree debugger
Stars	約 35
Forks	20
主な言語	TypeScript
License	MIT
Current npm version	1.1.0

Inner loop の observability を補う

多くの team には production observability があります。Log platform、trace collector、dashboard、alerting などです。ただし agent development の inner loop は、もっと素朴なことが多いです。Local で eval を走らせ、prompt を少し変え、tool call の順序を調整し、もう一度実行する。

この段階で全てを production-grade observability stack に接続するのは、少し重い場合があります。欲しいのは、次の質問にすぐ答える小さな tool です。

この run はどの step を通ったのか。
どの tool call が一番遅かったのか。
Failure はどの nested step で起きたのか。
Prompt を変えた後、execution path は変わったのか。
Trace を Markdown に export して PR や postmortem に貼れるか。

agent-inspect の README は、これを local-first tool として位置づけています。Account は不要で、cloud upload も dashboard も前提にしません。Production observability platform を置き換えるものではなく、agent developer の手元で使う trace magnifier に近いです。

基本の使い方は軽い

Install は普通の npm package です。

npm install agent-inspect

Code では inspectRun で agent run を包み、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

この model の良さは控えめなところです。最初から完全な trace schema を設計する必要はありません。Service 全体を作り替える必要もありません。重要な step を包むだけで、local JSONL trace と読みやすい tree が得られます。

既存の structured logs も利用できる

すでに pino、winston、log4js、NestJS logger、custom JSONL event stream を持つ project もあります。その場合、すべての function を新しく step で包むのは現実的ではないかもしれません。

agent-inspect の logs command はこの経路を扱います。既存 log から run id、event、timestamp などの field を読み、flat log を timeline や tree に整理します。

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

README の境界線も慎重です。JSON logs は first-class。log4js-style text line は best-effort。JavaScript object literal を log interchange format として eval しない。Agent trace には user input、tool output、model text が混ざりやすいため、この安全側の姿勢は重要です。

1.1.0 は controlled tracing と trace safety が中心

CHANGELOG.md によると、1.1.0 の変更は実用寄りです。

maybeInspectRun() が追加され、AGENT_INSPECT environment variable で trace writing を制御できる。
inspectRun に enabled option が入り、不要なときは passthrough にできる。
Manual trace metadata の redaction と event / metadata size bound が default-on になった。
LangChain adapter が opt-in の JSONL persistence をサポートした。
pino、log4js、NestJS など structured logging recipes が追加された。
ESM / CommonJS TypeScript consumers 向けの conditional type exports が修正された。

これは、実際の team がすぐ困るところを埋めている印象です。Eval harness や CI では、毎回 trace を書きたいわけではありません。失敗 sample を調べるときだけ environment variable で有効にするほうが自然です。また trace file には sensitive metadata や巨大 payload が入りやすいので、default redaction と size bound は後付けの注意書きより実用的です。

CLI commands が debugging loop を一通り覆う

README にある CLI commands は、local debugging loop をかなり広く覆っています。

list: 最近の runs を探す。
view: ある run を tree として見る。
clean: 古い trace files を安全に削除する。
logs: 既存 structured logs を tree / timeline に変換する。
tail: app 実行中の log を追う。
export: Markdown、HTML、OpenInference-compatible JSON、OTLP JSON を local に書き出す。
diff: 二つの local runs を比較する。

特に diff と export は重要です。Agent の問題は単発の failure だけではありません。「変更前後で挙動が変わった」ことが本体になる場合があります。Prompt や routing を変えた後に、run tree が 3 steps から 7 steps へ増えたり、fallback が頻繁に発火したりするなら、final answer だけを見るより早く気づけます。

export は collaboration に向いています。Local trace を Markdown にして PR、issue、internal postmortem に貼るほうが、screenshot や散らばった log より review しやすいです。OpenInference / OTLP JSON export は compatibility-oriented であり、default で backend に upload するものではありません。

Optional LangChain adapter と TUI

Core package の外には optional components もあります。

@agent-inspect/langchain: LangChain.js callback adapter。Metadata-oriented が default で、persist: true のときだけ persistent trace を書く。
@agent-inspect/tui: Terminal interactive viewer。view --tui のような使い方に向く。

どちらも incremental adoption path として使いやすいです。既存の LangChain.js project は callback から始められます。Interactive view が必要な人は TUI を足せます。一方で README は、これらの programmatic surfaces が experimental、または core API とは別に進化する可能性があることも書いています。Production dependency は安定した core API と CLI を中心に置くのがよさそうです。

どんな team に合うか

私は次のような team に向いていると思います。

TypeScript / Node.js agent を作っていて、今は console log 中心で debugging している。
Eval や CI sample があり、failure 時に local trace artifact を残したい。
Structured JSON logs はあるが、同じ run を readable tree にまとめる tool がない。

向かない場面もはっきりしています。Production dashboard、cross-service distributed tracing、cost analysis、replay system、hosted vendor platform が必要なら、agent-inspect はその製品ではありません。価値は、小さく、近く、local で、development loop に置けることです。

まとめ

rajudandigam/agent-inspect が面白いのは、AI agent debugging をまた一つの大きな platform にしないところです。まず基本的な causality を戻します。一回の run で、どの step が起き、何が何に nested し、どの tool が遅く、どの LLM call が失敗し、二回の path がどう違うのか。

Agent が demo から実際の product に近づくほど、debugging の単位は「final answer を見る」から「execution process を見る」へ移ります。agent-inspect は、その変化に必要な実用的な一部を提供します。Local JSONL trace、terminal tree、log ingestion、diff、export。Small team には、これで十分な場面が多いはずです。