agent-inspect: local JSONL traces and deterministic trajectory checks for TypeScript agents

The failure agent-inspect is built for: a run that succeeds but takes the wrong path

Agent code rarely fails as one function call. The README's own framing is that an agent plans, retrieves, calls tools, invokes a model, retries, and produces side effects, and that flat logs show only fragments of that sequence. A run can return a plausible answer while skipping a required retrieval step or hitting a tool that should not have been reachable. Ordinary logging will not tell you that, because the final output looks fine. AgentInspect targets that gap: it keeps a run as local JSONL and derives an execution tree from it, so the first causal failure and the ordering of tool and model calls are inspectable after the fact. The intended user is a TypeScript developer working on an agent who already has logs or instrumentation and wants a structured view without standing up a backend. The three advertised jobs (debug, prevent, share) all read the same captured trace, which is the design bet: one capture, three consumers.

How the evidence loop works: JSONL in, tree, check result and bundle out

The mechanism is a local run directory, named `.agent-inspect` in every README example, holding JSONL records that AgentInspect reads back. Trace data can arrive by manual instrumentation, official adapters, supported standards files, or structured logs you already emit. From that store the CLI renders a nested view of steps, tool calls, LLM calls, model and token metadata, durations, errors, and what the project calls the first causal failure. The check path is separate and deliberately narrower: checks are described as deterministic and provider-free, meaning the same trace plus the same rules produce the same result, with no model call in the loop. That property is what makes the exit code usable as a CI gate. The bundle path is a third consumer of the same records: `bundle` writes a redacted artifact plus a manifest, and `bundle verify` rechecks the listed file hashes offline. The README describes `verify-safe` as a best-effort local assessment that can return SAFE, SAFE WITH WARNINGS, UNSAFE, or UNKNOWN, and states plainly that share-checked is not compliance certification. That caveat is worth taking literally: the tool tells you what it found, not what a reviewer or regulator will conclude.

Getting a first trace without an API key

The install is a single package. `npm install agent-inspect` does not copy repository examples into your project; `init` writes them. The documented first-run sequence is `npm install agent-inspect`, then `npx agent-inspect init --yes`, then `node examples/agent-inspect-demo.mjs`, then `npx agent-inspect list --dir .agent-inspect`. The generated demo is synthetic, keyless and local, so you can confirm the pipeline before pointing it at real agent code. Copy the printed run ID and inspect it with `npx agent-inspect view <run-id> --dir .agent-inspect --summary`, `npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectory`, and `npx agent-inspect verify-safe <run-id> --dir .agent-inspect`. For a fixed walkthrough the README points at a canonical keyless showcase with stable run IDs: demo-good, demo-regression and demo-pii. If you want the richer framework-specific paths, the blessed starters directory covers those. One packaging detail matters for adoption: the framework integrations are separate packages, so LangChain and LangGraph users install `@agent-inspect/langchain`, AI SDK users install `@agent-inspect/ai-sdk`, and OpenAI Agents JS users install `@agent-inspect/openai-agents`. The core package is not a universal adapter.

The CI gate: exit codes, presets and the flags that define a trajectory

The check command is where the project earns its place in a pipeline. The README example is `npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectory --required-tool retrieve_policy --fail-on-observation failed`. A passing check exits 0 and a rule failure exits 1. Invalid configuration and unreadable or unsupported inputs use separate documented exit codes, which matters if your CI distinguishes between a broken agent and a broken test harness. The flags shown map directly onto trajectory assertions: `--required-tool` names a tool that must appear in the run, and `--fail-on-observation failed` turns a failed observation into a failing check. The README advises starting from a preset and extending it with the expectations that matter to the workflow. When a single CLI check is not enough, the documented escalation path is TraceContract, suites, cohorts, Vitest or Jest reporters, or `--evidence-on fail`. The Vitest and Jest reporters ship as their own packages, `@agent-inspect/vitest` and `@agent-inspect/jest`, so the CI integration is a real dependency rather than a shell wrapper around the CLI.

Where the local-first design costs you something

The absence of a collector is the feature and the constraint. There is no account, no default upload, and metadata-only capture by default, which means there is no server-side query across runs, no retention policy you did not write, and no shared dashboard for a team that is not on the same machine or artifact store. Correlation across services or across machines is your problem, not the tool's. The second limitation is the safety assessment itself. `verify-safe` is explicitly best-effort and can return UNKNOWN, which is the honest answer when the tool cannot classify what it sees; a CI job that treats UNKNOWN as a pass is misusing it. Third, the check layer only knows what is in the trace. If your instrumentation never records a tool call, `--required-tool` cannot fail on it, and a green check means the rule matched the recorded evidence, not that the agent behaved correctly. Finally, this is a Node.js 20 or newer package, and the adapter model means unsupported frameworks need manual instrumentation or the log-to-tree path before any of the trajectory checks are usable.

How this differs from hosted tracing and from plain log aggregation

The obvious alternative is a hosted observability platform in the OpenTelemetry or LLM-tracing family: you send spans to a service, and the service gives you a UI, retention and cross-run search. The difference in approach is where the data lives and what runs over it. A hosted platform centralizes collection and makes the trace a queryable record on someone else's infrastructure; AgentInspect keeps the run as local JSONL and makes the trace an input to deterministic rules that run on your machine or in your CI job. That trade favors teams with data-handling constraints or a preference for provider-free checks, and it costs them the shared UI. A second alternative is the log aggregation you may already run: it can store and search text, but it does not know what a trajectory is, so it cannot express `--required-tool retrieve_policy` or distinguish exit 1 from an invalid-config exit. AgentInspect's log-to-tree path (`npx agent-inspect logs ...`) is the bridge for teams that already emit structured logs and do not want to re-instrument. Note that the standards path (`npx agent-inspect open ...`) accepts OpenInference and OTLP JSON files, so the project is not asking you to abandon existing trace formats, only to process them locally.

Maintenance surface, release cadence and licence

The repository shows a fast release cadence: agent-inspect 6.18.0 and 6.19.0 were both published on 2026-09-06, alongside @agent-inspect/vitest 6.19.0 the same day. The core package and the test reporters are versioned together, which simplifies pinning, but the adapter packages listed in the stack table are separate installs and should be pinned as well. Plan for upgrade cost in two places: the JSONL record shape that `view`, `check` and `bundle` all read, and the check configuration surface (presets, required tools, fail-on-observation). Because checks are deterministic and provider-free, a rule change is a code review item rather than a model-behaviour question, which makes upgrades easier to reason about than a hosted platform's schema migrations. The licence is MIT, so you can use it commercially and modify it; the repository also ships a LICENSE file. This is not legal advice, and the README's own warning applies to any artifact you redistribute: review the bundle before attaching it to a PR, incident or support handoff, since share-checked is a local assessment and not a certification.

Editorial conclusion

Adopt agent-inspect if you run TypeScript agents on Node 20 or newer and want trajectory assertions in CI without shipping traces to a collector, and if the frameworks you use are covered by the adapters listed in the support table. Do not adopt it if you need a hosted dashboard with cross-service querying or trace retention you do not manage yourself; the project explicitly has no account, no collector and no default upload. Before wiring it into a pipeline, run `npx agent-inspect init --yes` plus the generated demo to confirm the JSONL layout matches what your agent emits, then decide whether `verify-safe` output is acceptable for the artifacts you plan to attach to a PR.

Official sources

1. License: MIT
2. Project website
3. rajudandigam/agent-inspect on GitHub
4. README
5. Releases