npm install agent-inspect

Four pillars

| Pillar | What you get | | ------ | ------------ | | Capture faithfully | Framework-aware execution trees and local JSONL you own | | Test behavior deterministically | TraceFacts, TraceContract, checks, suites, gates, and experimental Vitest/Jest matchers | | Produce portable evidence | Offline Evidence v2 with integrity verification and share-policy disclosure | | Debug with coding assistants locally | Read-only MCP over the same TraceFacts — no collector required |

1. Capture one real run
2. Find the causal failure
3. Ask your coding agent to inspect it
4. Lock the fix with a contract
5. Attach the share-checked evidence

Five-minute path

Commands below match the packed quickstart. Replace <run-id> with a value from list.

npm install agent-inspect
npx agent-inspect init --yes
# or: npx agent-inspect init --framework langgraph --yes
node examples/agent-inspect-demo.mjs
npx agent-inspect list --dir .agent-inspect

# After copying a run id from list:
npx agent-inspect report <run-id> --dir .agent-inspect
npx agent-inspect check <run-id> --dir .agent-inspect
npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share
npx agent-inspect verify-safe <run-id> --dir .agent-inspect
npx agent-inspect bundle verify .agent-inspect/bundles/<run-id>
# Optional coding-agent loop (dry-run by default):
npx agent-inspect mcp configure --client cursor

Guides: First trace in 5 minutes · Golden path · Coding-agent loop

Why AgentInspect

Category: the local evidence debugger and trajectory-test toolkit for TypeScript AI agents — not a hosted APM, eval host, or prompt registry. Complements LangSmith/Langfuse/Phoenix; owns the laptop → PR loop.

Proof (public-safe): Validated against production-shaped NestJS/LangGraph integrations. Fixture-backed across official adapters and packed consumer workflows.

| Mechanism | What you get | | --------- | ------------ | | Faithful execution trees | Nested steps, tools, LLMs, status, duration on disk | | TraceFacts / logical projection | Canonical tool identity and semantic parity without inventing hierarchy | | Deterministic checks / TraceContract (Beta) | Trajectory expectations without an LLM judge | | Experimental Vitest/Jest matchers | toPassTraceContract · toHaveRequiredTool | | Share-checked Evidence v2 | bundle + bundle verify with optional TraceFacts semantics | | Read-only MCP coding-agent loop (Preview) | get_trace_facts and related tools over local traces |

Choose your capture path

| Path | Use when | Start | | ---- | -------- | ----- | | Manual / observe | Custom nesting or object methods | Getting started | | AI SDK | Vercel AI SDK generateText / streamText | @agent-inspect/ai-sdk | | OpenAI Agents | OpenAI Agents JS | @agent-inspect/openai-agents | | LangChain / LangGraph | Callbacks / LangGraph | @agent-inspect/langchain · init --framework langgraph | | Structured logs | Logs already emitted | Log-to-tree | | Harness | Fixture runner for real projects | @agent-inspect/harness | | CI reporters + matchers | Failed-test artifacts and contracts | vitest · jest | | Standards files | OpenInference / OTLP JSON | Standards |

Blessed starters (no API keys): examples/starters · LangGraph gate/evidence recipe: langgraph-gate-evidence

What you can do after capture

Understand — what / view / tree · timeline · report · diff · buildTraceFacts

Prevent regressions — deterministic checks · TraceContract (Beta) · suites · cohorts · CI gates · Vitest/Jest reporters · experimental matchers (toPassTraceContract, toHaveRequiredTool)

Share safely — redaction profiles · scan · verify-safe · Evidence v2 bundles · CI artifacts

Debug with coding assistants — @agent-inspect/mcp-server · get_trace_facts · first-causal-failure

Scale locally — workspace · optional SQLite index (Beta) · viewer / TUI / VS Code · customer-owned Studio (Beta)

Support labels: SUPPORT-LEVELS.md · Network: NETWORK-BEHAVIOR.md · No-egress: NO-EGRESS-POLICY.md

Real-world scenarios

| Scenario | Start | | -------- | ----- | | Wrong tool / intentional failure | broken-agent-debugging | | Coding-agent MCP debug loop | coding-agent-debug-loop · CODING-AGENT-LOOP | | CI trajectory gate + Evidence | ci-eval-redact · langgraph-gate-evidence | | Safe incident handoff | Safe sharing | | Multi-agent / session retry | Sessions & outcomes | | Customer-owned team review | Self-hosting · Studio (optional) |

Safety and network behavior

• Traces are local JSONL under .agent-inspect/ (or AGENT_INSPECT_TRACE_DIR)
• Metadata-only by default — no raw prompts/outputs unless you opt in
• No hidden upload — core does not send traces to AgentInspect
• Customer-owned Studio ingestion is disabled by default and explicit when enabled
• MCP server exposes configured local evidence to the connected client (Preview)
• Standards export only when you run/configure it
• Redaction is best-effort, not certification — review before posting
• Not a chain-of-thought recorder

Details: Safe sharing · Network behavior · Security

Project status

Current release: 6.14.1 · schema 1.0 · Node.js ≥ 20 · MIT · actively maintained (eighteen linked npm packages).

The 6.14 line is actively maintained for correctness, compatibility, documentation, security, and framework evolution.

Roadmap · Changelog · Public product facts

What AgentInspect is not

• Hosted SaaS or maintainer-hosted dashboard
• Production APM replacement
• Eval dataset platform or LLM-as-judge by default
• Prompt registry, pricing engine, or replay engine
• Universal standards exporter
• Compliance certification

See Compare.

Canonical tiers: POSITIONING-AND-PORTFOLIO.md · SUPPORT-LEVELS.md.

Tier A — Flagship

| Package | Purpose | | ------- | ------- | | agent-inspect | Core APIs + CLI + evidence | | @agent-inspect/redact | Deterministic redaction | | @agent-inspect/mcp-server | Read-only MCP coding-agent loop (Preview) |

Tier B — Official integrations

Framework adapters

| Package | Purpose | | ------- | ------- | | @agent-inspect/ai-sdk | AI SDK telemetry | | @agent-inspect/openai-agents | OpenAI Agents processor | | @agent-inspect/langchain | LangChain / LangGraph callbacks |

Tier B — Testing / evaluation

| Package | Purpose | | ------- | ------- | | @agent-inspect/harness | Fixture runner | | @agent-inspect/eval | Local eval heuristics | | @agent-inspect/vitest | Vitest reporter + experimental matchers | | @agent-inspect/jest | Jest reporter + experimental matchers |

Tier C — Optional supporting (Safety)

| Package | Purpose | | ------- | ------- | | @agent-inspect/redact | Deterministic redaction | | @agent-inspect/guardrails | Deterministic guardrail rules | | @agent-inspect/circuit | Loop / retry / timeout analyzers |

Tier C — Optional supporting (Developer surfaces)

| Package | Purpose | | ------- | ------- | | @agent-inspect/viewer | Localhost viewer | | @agent-inspect/tui | Optional terminal UI | | @agent-inspect/mcp | MCP client tracing | | @agent-inspect/mcp-server | Read-only MCP server (Preview) |

Tier C — Optional supporting (Team / self-hosted)

| Package | Purpose | | ------- | ------- | | @agent-inspect/index-sqlite | Optional SQLite index (Beta) | | @agent-inspect/studio | Customer-owned Studio (Beta) |

Tier C — Optional supporting (Extension / interop)

| Package | Purpose | | ------- | ------- | | @agent-inspect/adapter-sdk | Third-party adapters (Beta) |

agent-inspect-vscode is in-repo (Marketplace not published yet).

Documentation

| | Website | Repo | | - | ------- | ---- | | Getting started | docs | FIRST-TRACE | | TraceFacts / contracts | — | TRACE-FACTS · TRACE-CONTRACTS | | Evidence / MCP / no-egress | — | EVIDENCE-FORMAT · CODING-AGENT-LOOP · NO-EGRESS-POLICY | | Safe sharing | safe-sharing | SAFE-TRACE-SHARING | | API / CLI | — | API · CLI (packed with npm) | | Full index | — | docs/README.md |

Contributing

CONTRIBUTING.md · Good first issues · Discussions

Redact traces before posting issues or PRs.

pnpm add agent-inspect
npx agent-inspect doctor

Monorepo: pnpm install && pnpm build && pnpm test