agent-inspect · Local-first trace + check + redact

Debug TypeScript AI agents locally

Trace what happened, check what should have happened, and redact what must not leave your machine. No account. No upload. Metadata-only by default.

npm install agent-inspect

First trace in 5 minutes View on GitHub

Open sourceMIT licenseTypeScriptLocal-first

agent-inspect · local terminal

$ npx agent-inspect init --framework ai-sdk
✓ created agent-inspect.config.ts
✓ wrote .agent-inspect/demo-support-agent.jsonl

$ npx agent-inspect view demo-support-agent
support-agent 1.8s ✓
├─ classify intent 120ms ✓
├─ search knowledge base 740ms ✓
├─ draft response 890ms ✓
└─ verify-safe 40ms ✓

The problem

console.log was not built for agents

Agent runs are nested, parallel, tool-heavy, and privacy-sensitive. Flat logs tell you something happened. They rarely show what happened in order, where it branched, or what is safe to share.

Flat logs hide nested decisions

You see a tool name, not the parent run, siblings, or where the branch went wrong.

Parallel tool calls get interleaved

Concurrent work collapses into a stream of lines without step boundaries.

Hosted dashboards slow the local loop

Accounts, ingestion, and dashboards are great for fleets — not for the first failing run on your laptop.

Raw traces can leak customer data

Without redaction and verify-safe, PR and issue attachments can expose more than you intended.

Five-minute path

One trace, one check, one safe artifact

Install, run the deterministic demo, inspect the tree, check completion and stalls, then redact before you share.

The deterministic starter path works without API keys.

bash

npm install agent-inspect
npx agent-inspect init --yes
node examples/agent-inspect-demo.mjs
npx agent-inspect list --dir .agent-inspect
npx agent-inspect view <run-id> --dir .agent-inspect
npx agent-inspect check .agent-inspect/*.jsonl --require-completed --detect-stalls
npx agent-inspect redact --profile share --dir .agent-inspect
npx agent-inspect verify-safe --dir .agent-inspect

Product loop

The local agent debugging loop

Capture

Capture manual steps, AI SDK telemetry, OpenAI Agents traces, LangChain callbacks, logs, harness runs, and CI/test artifacts.

Inspect

Read local JSONL as trees, timelines, reports, terminal output, viewer artifacts, or editor-friendly traces.

Check

Turn expectations into deterministic checks for completion, stalls, failures, regressions, and CI review.

Redact

Create share-safe artifacts before opening issues, reviewing PRs, or talking with design partners.

Features

Built for the TypeScript agent inner loop

Local JSONL traces

Own your runs as files under `.agent-inspect/`. No account required.

Execution trees

Nested steps, tool/LLM types, durations, and status in a readable tree.

Metadata-only by default

Safe defaults keep prompts and outputs out of traces unless you opt in.

Framework adapters

AI SDK, OpenAI Agents, LangChain, plus manual and log-ingest paths.

CI checks and reporters

Deterministic `check`, `eval`, and Vitest/Jest reporters for PR evidence.

Redaction profiles

`local`, `share`, and `strict` profiles before issues, PRs, or partner threads.

Viewer, TUI, and VS Code surfaces

Inspect locally in terminal, localhost viewer, or the in-repo VS Code extension.

OpenTelemetry and OpenInference export path

Compatibility-oriented local exports when you need a bridge to platform tooling.

Code

Start from the path you already use

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

await inspectRun("support-agent", async () => {
  const intent = await step("classify intent", () =>
    classifyIntent(ticket)
  );

  const docs = await step.tool("search knowledge base", () =>
    searchKnowledgeBase(intent)
  );

  return step.llm("draft-model", () =>
    generateResponse(docs)
  );
});

Use cases

Where teams use AgentInspect today

Debug a wrong tool call locally

See the tool step, siblings, and parent run without leaving your terminal.

Attach a safe trace to a PR

Redact with the share profile, verify-safe, then attach the local artifact.

Catch stalled agent runs in CI

Use deterministic checks for completion and stalls on fixture traces.

Compare before/after agent behavior

Diff two local runs when a prompt, tool, or model change lands.

Build a community adapter

Use the adapter SDK and conformance guidance for third-party frameworks.

Review traces in VS Code without a hosted dashboard

Open local JSONL in the in-repo extension while you stay on disk.

Compare

Complementary, not a replacement

Use AgentInspect for the local developer loop. Use hosted platforms or OpenTelemetry for production observability. They can complement each other.

Capability	agent-inspect	console.log	Hosted observability	Raw OpenTelemetry
Local-first	Yes — traces on disk	Yes	Usually account + ingestion	Depends on collector/backend
Account required	No	No	Usually yes	No for SDK; yes for many backends
Upload required	No by default	No	Usually yes	Exporter/collector dependent
Execution tree	Built-in	Flat stream	Often yes	Spans/traces with setup
CI checks	Deterministic CLI checks	Manual	Platform-specific	Custom pipelines
Safe redaction flow	Profiles + verify-safe	Manual	Varies	Custom
Team dashboard	Not the goal	No	Yes	Via backend/viewer
Production monitoring	Not the goal	No	Yes	Yes, with platform setup
Best for	Local dev, CI artifacts, safe sharing	Tiny scripts	Production fleets and team collaboration	Platform observability foundation

Boundaries

Local-first by design. Not a hidden platform.

Not a hosted SaaS dashboard
Not a production APM replacement
Not an eval dataset platform
Not a prompt registry
Not a hidden uploader
Not a chain-of-thought recorder
Not a replay engine

Open source trust

Transparent defaults you can audit

AgentInspect is MIT-licensed, dependency-light at the root, and explicit about network behavior: no upload by default.

MIT license Local JSONL files Metadata-only default Redaction profiles verify-safe before sharing GitHub issues and discussions npm package Technical guide Safe trace sharing docs

FAQ

Straight answers

Is AgentInspect a replacement for LangSmith or Langfuse?+

No. It complements hosted observability tools. AgentInspect focuses on the local developer loop: traces on disk, CLI checks, and safe sharing.

What does it capture by default?+

Metadata-only by default. Prompts and outputs are not captured unless you explicitly opt into content capture settings.

Does it upload traces?+

No upload by default. Traces are local files unless you explicitly export or share them.

Which frameworks does it support?+

Manual instrumentation, Vercel AI SDK (`@agent-inspect/ai-sdk`), OpenAI Agents (`@agent-inspect/openai-agents`), LangChain (`@agent-inspect/langchain`), structured logs, harness, and CI/test reporters.

Can I use it in CI?+

Yes. Run `check`, `eval`, `artifacts`, and `verify-safe` on local traces, then upload redacted artifacts with your CI platform.

Can I share traces safely?+

Use `redact --profile share` (or `strict`) and `verify-safe` before attaching traces to PRs or issues. Profiles are best-effort safeguards, not compliance certifications.

Is it production monitoring?+

No. Use hosted platforms or OpenTelemetry for production fleets and team dashboards.

Does it record chain-of-thought?+

No. AgentInspect does not record chain-of-thought.

How much does it cost?+

It is open source under the MIT license.

Where are the docs?+

Starter docs live at https://agentinspect.vercel.app/docs/. Canonical GitHub docs remain the full reference during migration.

Get your first local trace in five minutes

Install AgentInspect, run the deterministic demo, and keep traces on your machine.

npm install agent-inspect

Read the docs Star on GitHub