AgentInspect (agent-inspect) is a local-first evidence debugging and trace testing toolkit for TypeScript AI agents. Its positioning is to let developers see clearly what an agent actually did, to catch incorrect tool paths in CI, and to keep evidence local. Its core idea is to record agent runs as local JSONL, and to accomplish three things based on the same trace: debugging, prevention, and sharing.
Purpose and Main Capabilities
Debugging: Display nested steps, tool calls, LLM calls, model and token metadata, timing, errors, and the first causal failure as a readable execution tree, without sending traces to the AgentInspect service. Traces can be obtained through manual instrumentation, official adapters, supported standard files, or existing structured logs.
Prevention: Checks are deterministic and do not depend on the model provider; the same trace and rules always produce the same result. You can start from presets and then extend expected rules according to your workflow. Using --fail-on-observation failed takes effect only when the run has recorded an explicit OUTCOME event; trace checks will not infer outcomes from tools, LLM, or run success. A passing check has exit code 0, a rule failure has exit code 1, and invalid configuration and unreadable or unsupported input use separately documented exit codes. When more than one CLI check is needed, you can use TraceContract, suites, cohorts, Vitest/Jest reporters, or --evidence-on fail.
Sharing: verify-safe is a local best-effort assessment that can return SAFE, SAFE WITH WARNINGS, UNSAFE, or UNKNOWN; bundle writes redacted artifacts and a manifest, and bundle verify revalidates the file hashes listed in the manifest while offline. "Share-checked" is not a compliance certification; artifacts should be manually reviewed before being attached to a PR, incident, or support handoff.
How to Use
First install and initialize: npm install agent-inspect will not copy the repository examples; init will write them into the project. What is generated is a synthetic, key-free, local demo. Copy the printed run ID and then perform the check. Officially, good/regression demos with stable run ids (demo-good, demo-regression, demo-pii) are also provided.GUI/PII fixed demo, plus curated introductory examples covering specific framework paths.
The programmatic trace inspection API also exposes TraceFacts for bounded, logical analysis of supported traces, as detailed in the programmatic trace analysis documentation.
Applicable scenarios and limitations
AgentInspect is responsible for the evidence closed loop from laptop to PR, complementing hosted observability, production trace retention, and generalized evaluation platforms rather than replacing them. It is not intended for the following uses: a maintainer-hosted SaaS or production APM replacement, hosted trace retention, team dashboard service or prompt registry, a default LLM-as-judge or dataset platform, a replay engine, an automated repair system, or compliance certification. It is also not a chain-of-thought recorder.
Security and network behavior
Traces are local JSONL located under .agent-inspect/ or AGENT_INSPECT_TRACE_DIR. Collection is metadata-only by default; raw prompts and outputs must be explicitly enabled. Redaction is enabled by default at write time; the redact command creates a separate redacted copy and does not modify the source file. Core collection and inspection do not require an AgentInspect account, collector, or default upload. Redaction and verify-safe are best-effort controls, not privacy, security, or compliance certifications. The optional MCP, standard exports, and customer-owned Studio interface are explicit and each has its own network boundaries.
Optional coding agent loop
@agent-inspect/mcp-server exposes configured local evidence to MCP clients through bounded, read-only tools; it is optional and currently in Preview, and the core debug/inspect/evidence loop does not depend on it. Before enabling it, review the generated dry-run configuration and the coding agent loop guide. The root package is sufficient to support custom collection, CLI, inspection, and Evidence workflows; install optional packages only for the integrations or interfaces you use. agent-inspect-vscode currently lives in the repository and is not a published Marketplace extension.
Status and documentation
The current release baseline is 6.31.21, persistent schema 1.0, Node.js version requirement of at least 20, and MIT license. Legacy v0.1 and v0.2 traces can still be read; the current release version is subject to the npm badge and changelog. Before publishing traces in an issue or PR, you should first redact them with redact and review.
