Local execution trees for TypeScript AI agents.

agent-inspect helps you understand what happened inside an AI agent run — locally. It turns manual steps, tool calls, LLM calls, structured logs, failures, durations, and run metadata into readable execution trees you can inspect from the terminal.

It is built for TypeScript/Node.js developers and teams shipping real agentic products — not just toy demos. Use it for local TypeScript agent debugging, eval iteration, and CI trace artifacts. It complements production observability platforms; it does not replace them.

The tool starts with manual traces and existing structured logs, and extends into optional framework callbacks and standards-aligned local export — without turning the core into a SaaS or a vendor pipeline.

No account. No cloud upload. No dashboard required.

AI agents are no longer single function calls. They plan, call tools, invoke LLMs, branch, retry, fail, and run work in parallel. Console logs are flat; reconstructing causality from a wall of lines is slow and error-prone.

Hosted observability is valuable in production, but it can be heavy for the inner loop: local runs, fast iteration, and debugging before anything reaches a collector or dashboard.

agent-inspect gives those runs structure: an execution tree you can read and diff on disk, with a CLI-first workflow and no vendor lock-in.

Current npm release: 1.1.0.

npm install agent-inspect

pnpm add agent-inspect

Verify the CLI is available:

npx agent-inspect --help

For a clean npm/pnpm install checklist with ESM, CJS, and CLI checks, see Clean install smoke test.

Create demo.mjs:

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

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

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

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

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

Run it, then inspect the trace:

node demo.mjs
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

Full flow:

npm install agent-inspect
node demo.mjs
npx agent-inspect list --dir ./.agent-inspect

Simplified example output (actual CLI formatting may differ slightly):

support-agent
✔ plan
✔ tool:retrieve-policy
✔ llm:generate-answer

A runnable copy lives in examples/00-quickstart-demo.

Env-gated tracing (eval harnesses, CI): use maybeInspectRun and set AGENT_INSPECT=1 when you want a trace — otherwise no files are written.

import { maybeInspectRun } from "agent-inspect";

await maybeInspectRun("eval-case-42", async () => runAgent());

AGENT_INSPECT=1 node eval-runner.mjs

Each run produces a JSONL trace: run_started / run_completed, step_started / step_completed, with nested steps, tool/LLM types where you use step.tool / step.llm, and durations on completed steps. Failures are recorded on step_completed with status: "error" (there is no separate step_failed event). See docs/SCHEMA.md.

Many production systems already emit line-delimited JSON or text logs with embedded JSON (e.g. via pino, winston, log4js, NestJS loggers, job runners, or custom event streams). agent-inspect can turn those into local grouped timelines/trees without wrapping every function.

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

With a reusable ingest config:

npx agent-inspect logs ./agent.log --config agent-inspect.logs.json

• JSON logs are first-class.
• log4js-style lines are best-effort when a recoverable JSON payload is present.
• No eval, no JavaScript object-literal parsing as a log interchange format.
• Flat timeline by default; nesting when parent relationships are explicit or configured.
• Confidence labels (explicit, correlated, heuristic, unknown) describe how attribution was inferred.

More detail: docs/LOGS.md · docs/LOG-TO-TREE-QUICKSTART.md · docs/LOGGING-PLAYBOOK.md (pino, log4js, NestJS).

Full flags and behavior: docs/CLI.md.

• Debug a failed tool call or thrown error in a support or ops agent.
• See which step dominated latency in a multi-step planner or RAG pipeline.
• Diff two runs after a prompt, model, or routing change (see diff examples).
• Point logs / tail at existing job or service logs to get a local execution view without shipping data upstream.
• Export a run to Markdown for a PR, postmortem, or internal thread — then review before sharing.
• Keep traces on disk while still using enterprise observability elsewhere.

agent-inspect 1.x (current: 1.1.0) stabilizes the local debugging foundation:

• Instrument a run with inspectRun and step
• Write local JSONL traces (schemaVersion: "0.1" — compatibility retained)
• Inspect runs with list and view
• Safely remove old trace files with clean

Stable APIs: inspectRun(), maybeInspectRun(), step(), step.llm(), step.tool(), observe().

Pass enabled: false to inspectRun for a no-trace passthrough. Use maybeInspectRun with AGENT_INSPECT=1 (or true / yes / on / enabled) to toggle tracing in eval or CI jobs — see docs/API.md.

Stable CLI workflows: agent-inspect list, agent-inspect view, agent-inspect clean.

Also included in 1.x as local-first extensions:

• Structured log inspection: logs
• Live log tailing: tail
• Local exports: export (Markdown, HTML, OpenInference-compatible JSON, OTLP JSON — files only)
• Local run comparison: diff
• Optional @agent-inspect/langchain callback adapter
• Optional @agent-inspect/tui terminal viewer
• Fixtures and recipes for deterministic checks and adoption patterns

Honest boundaries: programmatic log parsing, export, and diff APIs; LangChain and TUI programmatic surfaces; and OpenInference/OTLP JSON exports are experimental or compatibility-oriented. Nothing performs vendor upload by default.

Optional package: official LangChain.js callbacks (BaseCallbackHandler), metadata-oriented by default, no monkey-patching, no vendor sink. The LangChain adapter ships with 1.x; its programmatic API remains experimental and may evolve independently of the stable core tracing API.

pnpm add agent-inspect @agent-inspect/langchain @langchain/core

import { AgentInspectCallback } from "@agent-inspect/langchain";

const callback = new AgentInspectCallback({
  runName: "support-agent",
  traceDir: "./.agent-inspect",
  persist: true,
  capture: "metadata-only",
});

await agent.invoke(input, { callbacks: [callback] });
// In-memory events still available:
const events = callback.getEvents();
// Persisted runs are inspectable via CLI:
// npx agent-inspect list --dir ./.agent-inspect
// npx agent-inspect view <run-id> --dir ./.agent-inspect

See examples/08-langchain-adapter and docs/ADAPTERS.md.

Optional Ink/React package, installed separately. Use with an interactive terminal:

pnpm add agent-inspect @agent-inspect/tui
npx agent-inspect view <run-id> --tui

The TUI is available as a separate optional package; its programmatic API is experimental, while the CLI integration (view --tui) is the intended usage. Details: docs/ADAPTERS.md.

Recipes are deterministic and require no external services by default. Index: examples/README.md, examples/recipes/README.md.

• Local files by default — no upload, no vendor sinks in core workflows.
• No API keys required for core tracing and CLI inspection.
• Manual metadata is user-controlled. By default, common sensitive keys are redacted before disk; pass redact: false to opt out. Long metadata is truncated and events are capped at 64 KiB per JSONL line. Review traces and exports before sharing.
• Review exports before sharing (especially with richer attribute flags).

See SECURITY.md and the safe trace sharing checklist.

It can complement LangSmith, Langfuse, Braintrust, Phoenix/OpenInference, OpenTelemetry, New Relic, Datadog, and similar platforms — but it does not replace their production or eval workflows.

For a detailed comparison, see Compare with other tools.

• Getting started
• Clean install smoke test
• API stability & experimental surfaces
• CLI reference
• Schema (schemaVersion: "0.1")
• Architecture (links to deeper design notes)
• Logs & tail
• Log-to-tree quickstart
• Logging playbook
• Exports
• Diff
• Adapters
• Compare with other tools
• Security
• Safe trace sharing checklist
• Changelog
• Known issues
• Limitations
• Screenshot checklist (planned assets)

AgentInspect welcomes docs, fixtures, examples, and carefully scoped CLI improvements.

• Good first issues: GOOD-FIRST-ISSUES.md — live batches #7–#14 and #18–#30 (comment on an issue before opening a PR)
• Discussions: github.com/rajudandigam/agent-inspect/discussions — feedback, stack survey, integration ideas
• Roadmap: ROADMAP.md — Now / Next / Future direction (non-committal)
• Contributing guide: CONTRIBUTING.md — validation commands, PR expectations, scope boundaries

Security: Traces and logs may contain secrets. Redact before sharing in issues, Discussions, PRs, or exports. See SECURITY.md and the safe trace sharing checklist.

From a clone of this repo:

pnpm install
pnpm build
pnpm test
pnpm test:all

To run the CLI from source after a build: node packages/cli/dist/index.cjs --help.