https://github.com/rajudandigam/agent-inspect

Local execution trees for TypeScript AI agents. agent-inspect helps you understand what happened inside an AI agent run — locally. It turns manual steps, tool calls, LLM calls, structured logs, failures, durations, and run metadata into readable execution trees you can inspect from the terminal. It is built for TypeScript/Node.js developers..
https://github.com/rajudandigam/agent-inspect

agent-observability agentic-ai ai ai-agent ai-debugging ai-logging-library ai-observability ai-systems braintrust langfuse langsmith local-logging logging multi-agent no-cloud no-cost observability opentelemetry typescript

Last synced: 9 days ago
JSON representation

Host: GitHub
URL: https://github.com/rajudandigam/agent-inspect
Owner: rajudandigam
License: mit
Created: 2026-05-02T06:07:29.000Z (3 months ago)
Default Branch: main
Last Pushed: 2026-07-09T02:52:26.000Z (15 days ago)
Last Synced: 2026-07-09T03:24:32.001Z (15 days ago)
Topics: agent-observability, agentic-ai, ai, ai-agent, ai-debugging, ai-logging-library, ai-observability, ai-systems, braintrust, langfuse, langsmith, local-logging, logging, multi-agent, no-cloud, no-cost, observability, opentelemetry, typescript
Language: TypeScript
Homepage: https://agentinspect.vercel.app
Size: 4.25 MB
Stars: 208
Watchers: 70
Forks: 88
Open Issues: 12
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md

Awesome Lists containing this project

awesome-infra-for-ai - rajudandigam/agent-inspect - Agent Inspect provides local execution trees, tracing, and debugging for TypeScript AI agents, offering in-depth insights into agent runs without cloud dependencies. (LLMOps / LLM Observability & Tracing)

README

          


  

    

    

  



agent-inspect




  Debug, regression-test, and safely share TypeScript AI-agent behavior—locally.





  _{No account · no default upload · metadata-only by default · optional customer-owned Studio}





  AgentInspect turns agent runs into customer-owned evidence: execution trees,

  deterministic contracts, CI gates, verified-safe bundles, and optional self-hosted review.





  Website ·

  Docs ·

  npm ·

  GitHub





  

  

  

  



```bash

npm install agent-inspect

```

## Three workflows

| Workflow | What you do |

| -------- | ----------- |

| **Debug one run** | Capture/import → tree / timeline / report → first causal failure |

| **Prevent one regression** | TraceContract / `check` → suite / cohort → CI gate |

| **Share one safe artifact** | Redact → `verify-safe` → offline bundle → optional Studio review |

**Review as a team (optional):** workspace + optional SQLite index → customer-owned [Studio Beta](https://github.com/rajudandigam/agent-inspect/tree/main/packages/studio) (no AgentInspect-hosted cloud).



  



## Five-minute path

Commands below match the packed quickstart. Replace `` with a value from `list`.

```bash

npm install agent-inspect

npx agent-inspect init --yes

node examples/agent-inspect-demo.mjs

npx agent-inspect list --dir .agent-inspect

```

```bash

# After copying a run id from list:

npx agent-inspect view  --dir .agent-inspect

npx agent-inspect report  --dir .agent-inspect

npx agent-inspect check  --dir .agent-inspect

npx agent-inspect bundle  --dir .agent-inspect --profile share

npx agent-inspect verify-safe  --dir .agent-inspect

```

`init` scaffolds config and a demo script; the **demo** writes the trace. Guide: [First trace in 5 minutes](https://agentinspect.vercel.app/docs/getting-started/) · [repo](https://github.com/rajudandigam/agent-inspect/blob/main/docs/FIRST-TRACE-IN-5-MINUTES.md) · [Golden path](https://github.com/rajudandigam/agent-inspect/blob/main/docs/GOLDEN-PATH.md)

## Choose your capture path

| Path | Use when | Start |

| ---- | -------- | ----- |

| **Manual / observe** | Custom nesting or object methods | [Getting started](https://github.com/rajudandigam/agent-inspect/blob/main/docs/GETTING-STARTED.md) |

| **AI SDK** | Vercel AI SDK `generateText` / `streamText` | [`@agent-inspect/ai-sdk`](https://www.npmjs.com/package/@agent-inspect/ai-sdk) |

| **OpenAI Agents** | OpenAI Agents JS | [`@agent-inspect/openai-agents`](https://www.npmjs.com/package/@agent-inspect/openai-agents) |

| **LangChain** | Callbacks / LangGraph-via-LangChain | [`@agent-inspect/langchain`](https://www.npmjs.com/package/@agent-inspect/langchain) |

| **Structured logs** | Logs already emitted | [Log-to-tree](https://github.com/rajudandigam/agent-inspect/blob/main/docs/LOG-TO-TREE-QUICKSTART.md) |

| **Harness** | Fixture runner for real projects | [`@agent-inspect/harness`](https://www.npmjs.com/package/@agent-inspect/harness) |

| **CI reporters** | Failed-test artifacts | [`vitest`](https://www.npmjs.com/package/@agent-inspect/vitest) · [`jest`](https://www.npmjs.com/package/@agent-inspect/jest) |

| **Standards files** | OpenInference / OTLP JSON | [Standards](https://github.com/rajudandigam/agent-inspect/blob/main/docs/STANDARDS.md) |

Blessed starters (no API keys): [examples/starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters)

## What you can do after capture

**Understand** — `what` / `view` / tree · timeline · report · diff · sessions / activity  

**Prevent regressions** — deterministic checks · typed TraceContract (Beta) · suites · cohorts · CI gates · Vitest/Jest reporters (artifact reporters today; TraceContract matchers not shipped)  

**Share safely** — redaction profiles · `scan` · `verify-safe` · offline bundles · CI artifacts  

**Scale locally** — workspace · optional SQLite index (Beta) · observed outcomes · viewer / TUI / VS Code  

**Review as a team** — customer-owned Studio Beta · explicit file / GitHub / HTTP ingest (disabled by default) · no maintainer cloud  

**Interoperate** — read-only MCP server (Preview) · OpenInference-compatible / OTLP GenAI-aligned mapping with known-loss reporting  

Support labels: [SUPPORT-LEVELS.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUPPORT-LEVELS.md) · Network: [NETWORK-BEHAVIOR.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NETWORK-BEHAVIOR.md)

## Real-world scenarios

| Scenario | Start |

| -------- | ----- |

| Wrong tool call | [broken-agent starter](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/broken-agent-debugging) |

| CI trajectory gate | [CI artifacts](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CI-ARTIFACTS.md) |

| Safe incident handoff | [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md) |

| Multi-agent / session retry | [Sessions & outcomes](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SESSIONS-AND-OUTCOMES.md) |

| Customer-owned team review | [Self-hosting](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SELF-HOSTING.md) · Studio |

| Design partner trial | [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md) |

## 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](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md) · [Network behavior](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NETWORK-BEHAVIOR.md) · [Security](SECURITY.md)

## Project status

**Current release:** **6.7.3** (eighteen linked npm packages). Technical launch candidate; external pilot evidence pending. Persisted schema **1.0**. Node.js **≥ 20**. **v7 not scheduled.**

[Roadmap](ROADMAP.md) · [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md) · [Changelog](CHANGELOG.md)

## 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 or completed external adoption proof

See [Compare](https://github.com/rajudandigam/agent-inspect/blob/main/docs/COMPARE.md).

Package family (18 public packages)

### Framework adapters

| Package | Purpose |

| ------- | ------- |

| [`agent-inspect`](https://www.npmjs.com/package/agent-inspect) | Core APIs + CLI |

| [`@agent-inspect/ai-sdk`](https://www.npmjs.com/package/@agent-inspect/ai-sdk) | AI SDK telemetry |

| [`@agent-inspect/openai-agents`](https://www.npmjs.com/package/@agent-inspect/openai-agents) | OpenAI Agents processor |

| [`@agent-inspect/langchain`](https://www.npmjs.com/package/@agent-inspect/langchain) | LangChain callbacks |

### Testing / evaluation

| Package | Purpose |

| ------- | ------- |

| [`@agent-inspect/harness`](https://www.npmjs.com/package/@agent-inspect/harness) | Fixture runner |

| [`@agent-inspect/eval`](https://www.npmjs.com/package/@agent-inspect/eval) | Local eval heuristics |

| [`@agent-inspect/vitest`](https://www.npmjs.com/package/@agent-inspect/vitest) | Vitest reporter |

| [`@agent-inspect/jest`](https://www.npmjs.com/package/@agent-inspect/jest) | Jest reporter |

### Safety

| Package | Purpose |

| ------- | ------- |

| [`@agent-inspect/redact`](https://www.npmjs.com/package/@agent-inspect/redact) | Deterministic redaction |

| [`@agent-inspect/guardrails`](https://www.npmjs.com/package/@agent-inspect/guardrails) | Deterministic guardrail rules |

| [`@agent-inspect/circuit`](https://www.npmjs.com/package/@agent-inspect/circuit) | Loop / retry / timeout analyzers |

### Developer surfaces

| Package | Purpose |

| ------- | ------- |

| [`@agent-inspect/viewer`](https://www.npmjs.com/package/@agent-inspect/viewer) | Localhost viewer |

| [`@agent-inspect/tui`](https://www.npmjs.com/package/@agent-inspect/tui) | Optional terminal UI |

| [`@agent-inspect/mcp`](https://www.npmjs.com/package/@agent-inspect/mcp) | MCP client tracing |

| [`@agent-inspect/mcp-server`](https://www.npmjs.com/package/@agent-inspect/mcp-server) | Read-only MCP server (Preview) |

### Team / self-hosted

| Package | Purpose |

| ------- | ------- |

| [`@agent-inspect/index-sqlite`](https://www.npmjs.com/package/@agent-inspect/index-sqlite) | Optional SQLite index (Beta) |

| [`@agent-inspect/studio`](https://www.npmjs.com/package/@agent-inspect/studio) | Customer-owned Studio (Beta) |

### Extension / interop

| Package | Purpose |

| ------- | ------- |

| [`@agent-inspect/adapter-sdk`](https://www.npmjs.com/package/@agent-inspect/adapter-sdk) | Third-party adapters (Beta) |

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

## Documentation

| | Website | Repo |

| - | ------- | ---- |

| Getting started | [docs](https://agentinspect.vercel.app/docs/getting-started/) | [FIRST-TRACE](https://github.com/rajudandigam/agent-inspect/blob/main/docs/FIRST-TRACE-IN-5-MINUTES.md) |

| Contracts / suites / gates | — | [TRACE-CONTRACTS](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-CONTRACTS.md) · [SUITES-COHORTS-GATES](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUITES-COHORTS-GATES.md) |

| Safe sharing | [safe-sharing](https://agentinspect.vercel.app/docs/safe-sharing/) | [SAFE-TRACE-SHARING](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md) |

| API / CLI | — | [API](docs/API.md) · [CLI](docs/CLI.md) (packed with npm) |

| Full index | — | [docs/README.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/README.md) |

## Contributing

[CONTRIBUTING.md](https://github.com/rajudandigam/agent-inspect/blob/main/CONTRIBUTING.md) · [Good first issues](https://github.com/rajudandigam/agent-inspect/blob/main/GOOD-FIRST-ISSUES.md) · [Discussions](https://github.com/rajudandigam/agent-inspect/discussions)

**Redact traces before posting issues or PRs.**

```bash

pnpm add agent-inspect

npx agent-inspect doctor

```

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

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/rajudandigam/agent-inspect

Awesome Lists containing this project

README

agent-inspect