AgentInspect Local Trace Toolkit
Inspect TypeScript agent runs locally and catch incorrect execution paths with deterministic CI checks.
- Source repo
- rajudandigam/agent-inspect
- Stars
- ★ 165
- Last updated
- 1d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 79/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A TypeScript agent developer reproducing a failed tool call locally and using the execution tree to find the first causal error.
- Not a fit if
- Teams that need hosted production monitoring and long-term trace retention
- Teams that need a prompt registry or online LLM evaluation platform
- Source review
- 79/100 · Good
What does this agent do, and when should you use it?
AgentInspect is a local-first toolkit for TypeScript AI agents that stores run traces as JSONL and provides a CLI, importable reader and checking APIs, and framework adapters. It renders nested steps, tool and LLM calls, durations, and errors as execution trees and reports to help locate causal failures. Trajectory presets, TraceContract, and suites let teams check recorded runs deterministically and fail CI on unmet rules. It can also write redacted Evidence v2 artifacts with a manifest and verify their file hashes offline. Core debugging, checking, and evidence workflows need no AgentInspect account or default upload; the runtime requirement is Node.js 20 or newer.
Install agent-inspect, use init to write examples, and run a demo to create a local trace; use list to find runs and view, report, or explain to inspect execution paths. The CLI check command evaluates runs against rules such as --preset trajectory and --required-tool; programmatic checks can read JSONL with openTraceFile and evaluate contracts with defineTraceContract and evaluateTraceContractRead. For sharing, run verify-safe to assess the trace, create an Evidence v2 artifact with bundle, and use bundle verify to check manifest hashes offline. Optional adapters cover LangChain/LangGraph, AI SDK, and OpenAI Agents JS; Vitest and Jest reporters and a Preview-stage MCP server are also available as optional packages.
- A TypeScript agent developer reproducing a failed tool call locally and using the execution tree to find the first causal error.
- An engineering team adding checks for required tools, workflow steps, or run completion to CI.
- A team using LangGraph, AI SDK, or OpenAI Agents JS instrumenting its framework with the corresponding adapter to inspect traces.
- An engineer attaching run evidence to a pull request, incident, or support handoff after creating a redacted, offline-verifiable Evidence v2 bundle.
- A team with structured logs or OpenInference/OTLP JSON bringing those records into a local inspection workflow with the
logsoropencommand.
How do you install or deploy this agent?
Requires Node.js >=20. Install the core CLI:
npm install agent-inspectCreate and run the local demo:
npx agent-inspect init --yes
node examples/agent-inspect-demo.mjs
npx agent-inspect list --dir .agent-inspectThe core workflow does not require an account or API key. For framework integrations, install the relevant adapter package listed in the README, such as @agent-inspect/langchain or @agent-inspect/openai-agents.
How do you use this agent?
Copy a run ID from list, inspect its summary, and run a trajectory check:
npx agent-inspect view <run-id> --dir .agent-inspect --summary
npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectoryCreate and verify shareable offline evidence:
npx agent-inspect verify-safe <run-id> --dir .agent-inspect
npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share --out ./evidence
npx agent-inspect bundle verify ./evidenceFor programmatic checks, read JSONL and evaluate a TraceContract:
import { openTraceFile } from "agent-inspect/readers";
import {
defineTraceContract,
evaluateTraceContractRead,
} from "agent-inspect/checks";
const read = await openTraceFile("./trace.jsonl");
const contract = defineTraceContract({
run: { requireCompleted: true },
tools: { required: ["retrieve_policy"] },
});
const result = evaluateTraceContractRead(read, contract);
if (result.status !== "pass") process.exitCode = 1;What are this agent's strengths and limitations?
- Traces stay in local JSONL by default, and core capture and inspection need no account, collector, or default upload.
- One trace supports execution-tree debugging, deterministic CI trajectory checks, and the Evidence v2 sharing workflow.
- Reader APIs, TraceContract, framework adapters, and Vitest/Jest reporters provide integration paths for TypeScript workflows.
- Requires Node.js >=20 and comfort with CLI commands or calling the APIs from code.
- Redaction and
verify-safeare best-effort controls, not privacy, security, or compliance certification; artifacts still need review before sharing. - Trajectory checks use recorded traces and rules; failure-based gating requires explicit OUTCOME events.
- The optional MCP server is currently Preview, which limits its suitability for teams requiring a stable MCP surface.
How does this agent compare with similar options?
The README positions AgentInspect as a laptop-to-PR evidence workflow that complements hosted observability/APM and eval/prompt platforms. Hosted observability suits production fleet monitoring and retention; eval/prompt platforms suit prompt and dataset management and online LLM-judge experiments.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| AgentInspect Local Trace Toolkit This agent | 79 · Good | CLIFree | ★ 165 | 1d ago | TypeScript | — |
| Open Generative UI | 44 · Major gaps | CLIFree + model costs | ★ 3k | 1d ago | TypeScript | Claude API |
| Open Multi-Agent Canvas | 43 · Major gaps | Web appFree + model costs | ★ 545 | 4mo ago | TypeScript | — |
| LangChain | 41 · Major gaps | Library / SDKFree + model costs | ★ 148k | today | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The docs describe local JSONL, metadata-only capture by default, write-time redaction, and opt-in raw prompts and outputs. The security policy also documents file modes, path boundaries, and read-only MCP/Viewer surfaces. Deductions: callers can disable redaction with redact:false, custom keys may bypass defaults, and exported files still require human review; the dependency review shown blocks high and critical advisories but no full audit result or inventory is provided. Publisher identity is unverified, so attribution evidence is limited.
The README describes trajectory checks, distinct exit codes, and offline evidence verification; package scripts and CI specify type, unit, integration, and packaging checks, while adapter tests cover capture settings and diagnostics. Deductions: these files show configured checks and test definitions, not successful execution for this revision; dependency ranges remain partly floating and failure-message detail is only partly evidenced.
The audience and scenarios are clear: TypeScript agent debugging, CI trajectory assertions, offline sharing, and several frameworks and log standards. The project explicitly excludes hosted APM, replay, automatic remediation, and compliance certification. Deductions: the documented runtime requires Node.js 20 or later and the ecosystem focus is TypeScript; activation is mainly through explicit CLI commands, library calls, or optional integrations.
The README, documentation index, and support-level guide provide a broad structure with installation, quick starts, CLI/API references, examples, limitations, migration, and changelog entry points. MIT licensing and a version baseline are explicit. Deductions: the large documentation set and 18-package family increase selection effort; the security policy says development is active but offers no formal SLA, and the responsible publisher/maintenance identity is not clearly established. A changelog reference alone does not establish maintenance quality.
Execution trees, deterministic trajectory rules, and verifiable offline evidence share one local trace and produce outputs suited to debugging and CI. No account or hosted service is needed by default, lowering infrastructure cost. Deductions: safe sharing still depends on human review and documented redaction limits; the package family and configuration may be excessive for users who only need simple log inspection.
README claims map to the security policy, package metadata, CI configuration, and concrete adapter test definitions. The docs distinguish best-effort safety checks from certification and state that tool/LLM success is not treated as a business outcome. Deductions: test files are definitions rather than run results, and safety/network claims are primarily documented assertions without independent corroboration in the supplied material.
- Redaction and verify-safe are best-effort; custom metadata keys may contain sensitive data, so inspect exports before sharing.
- This assessment uses only the supplied static files and does not verify passing test runs, runtime network behavior, or current dependency advisories.
FAQ
Do I need an account or API key for the core workflow?
Does it capture prompts and model outputs?
What happens when a CI check fails?
Does the safety check certify a bundle for compliance?
verify-safe is a best-effort local assessment, and the Evidence artifact should be reviewed before sharing.