Integrations

Manual instrumentation, framework adapters, logs, harness, CI reporters, and adapter SDK paths.

AgentInspect is framework-agnostic at its core. Optional adapter packages integrate specific frameworks without monkey-patching, vendor sinks, or network upload.

v2.3 hardening scorecard

v2.3 hardens existing official adapters before adding new ones. Priority is based on the current package set, open issue/adoption signals, conformance coverage, and how directly a framework can produce useful local traces without root/core dependencies.

Reporters (@agent-inspect/vitest and @agent-inspect/jest) are public packages as of v2.2, but they are CI/test artifact reporters rather than framework trace adapters. They stay outside the v2.3 adapter-hardening priority order.

Vercel AI SDK (@agent-inspect/ai-sdk)

Full guide: AI-SDK-ADOPTION.md

Status: experimental adapter — optional package published in the aligned v2.2.0 package set and hardened in the v2.3 adapter train.

The adapter has hardened lifecycle identity and parallel integration isolation. It remains metadata-only: capture: "preview" and preview-only redaction options emit diagnostics and fall back to metadata-only capture until bounded free-text previews are implemented.

Install

npm install agent-inspect @agent-inspect/ai-sdk ai

Local telemetry integration

import { generateText } from "ai";
import { agentInspect } from "@agent-inspect/ai-sdk";

const result = await generateText({
  model,
  prompt,
  experimental_telemetry: {
    isEnabled: true,
    recordInputs: false,
    recordOutputs: false,
    integrations: [
      agentInspect({
        traceDir: "./.agent-inspect",
        runName: "support-agent",
        capture: "metadata-only",
      }),
    ],
  },
});

• No monkey-patching — pass the integration explicitly through AI SDK telemetry.
• No upload behavior — the adapter writes only to an explicit local writer or traceDir.
• Metadata-only by default — records model, finish reason, token usage, timing, and safe counts/summaries.
• Required safe telemetry settings — set recordInputs: false and recordOutputs: false on every AI SDK call using this adapter.
• No raw payload capture by default — prompts, messages, generated text, stream chunks, tool inputs/outputs, headers, request bodies, and response bodies are not persisted.
• Preview capture is not enabled yet — capture: "preview", redactionProfile, and maxPreviewChars are diagnosed through getDiagnostics() and do not persist raw previews.

Local no-network recipe

examples/recipes/ai-sdk-local-telemetry uses AI SDK test utilities only (MockLanguageModelV3, simulateReadableStream) and writes local v0.2 adapter events for agent-inspect open.

examples/recipes/ai-sdk-next-route shows a route-style telemetry factory that creates one AgentInspect integration per request while keeping the same no-network, metadata-only defaults.

Common host shapes

Use the same explicit telemetry block shape for route handlers, streaming, and tool calls. Create a fresh agentInspect(...) integration per concurrent request/generation. The adapter does not wrap providers or change host-call settings.

const telemetry = {
  isEnabled: true,
  recordInputs: false,
  recordOutputs: false,
  integrations: [agentInspect({ traceDir: "./.agent-inspect", capture: "metadata-only" })],
};

// Next.js route or local handler
await generateText({ model, prompt, experimental_telemetry: telemetry });

// Streaming
await streamText({ model, prompt, experimental_telemetry: telemetry });

// Tool calls
await generateText({ model, prompt, tools, experimental_telemetry: telemetry });

Review recipe output with:

npx agent-inspect open ./examples/recipes/ai-sdk-local-telemetry/.agent-inspect-runs

Full API: API.md §11.

LangChain.js (@agent-inspect/langchain)

Status: experimental adapter — optional package published in the aligned v2.2.0 package set; programmatic API may evolve independently of stable core tracing.

Install

npm install agent-inspect @agent-inspect/langchain @langchain/core

Basic callback (in-memory)

import { AgentInspectCallback } from "@agent-inspect/langchain";

const callback = new AgentInspectCallback({
  runName: "support-agent",
  capture: "metadata-only", // default
});

await agent.invoke(input, { callbacks: [callback] });

const events = callback.getEvents();
callback.clear();

• No monkey-patching — pass the callback explicitly to LangChain.
• Metadata-only by default — does not capture full prompts/outputs unless you opt into capture: "preview".
• No vendor sink — events stay in memory unless you set persist: true.

Persist to local JSONL

const callback = new AgentInspectCallback({
  runName: "support-agent",
  traceDir: "./.agent-inspect",
  persist: true,
  capture: "metadata-only",
});

await agent.invoke(input, { callbacks: [callback] });

npx agent-inspect list --dir ./.agent-inspect
npx agent-inspect view <run-id> --dir ./.agent-inspect
npx agent-inspect export <run-id> --format markdown --redaction-profile share
npx agent-inspect eval <run-id> --dir ./.agent-inspect --require-success --json
npx agent-inspect redact ./.agent-inspect/<trace-file>.jsonl --profile share --json

eval and redact read local adapter traces only. They do not call model providers, upload traces, or loosen the adapter metadata-only capture defaults.

Synthetic demo — examples/08-langchain-adapter.

Persistence model (Strategy A):

1. Standalone session — one AgentInspect run per callback instance until the root LangChain run completes.
2. Inside inspectRun — callback steps append to the active manual run (no extra run_started / run_completed).
3. Parent mapping — LangChain parentRunId maps to AgentInspect parentId when the parent step was persisted; unknown parents stay at run root.
4. Step types — LLM → llm, TOOL → tool, DECISION → decision, other kinds → logic.

Written events use schemaVersion: "0.1" manual trace names.

LangGraph through LangChain callbacks

LangGraph-shaped callback metadata is covered through the existing @agent-inspect/langchain callback boundary. No separate @agent-inspect/langgraph package is shipped.

• Explicit callback only — pass new AgentInspectCallback(...) through LangChain/LangGraph callback configuration.
• Bounded graph metadata — known graph, node, subgraph, task, branch, checkpoint, retry, handoff, thread, and session identifiers are copied into attributes.langGraph when present.
• No full graph state — checkpoint/task/branch containers are summarized by type/count; raw graph state, prompts, tool payloads, outputs, and stream tokens are not stored in metadata-only mode.
• Conservative parent mapping — in-memory events preserve framework parentRunId; persisted JSONL maps parents only when the parent callback was seen, and marks unresolved parent mappings in step metadata.
• No hosted tracing requirement — fixtures use structural no-network callback payloads and do not require LangSmith, provider calls, or LangGraph platform services.

Capture modes

Streaming metadata (v1.3.0+)

const callback = new AgentInspectCallback({
  stream: true,
  capture: "metadata-only",
  persist: true,
});

When stream: true:

• handleLLMNewToken updates in-memory stats only — no per-token JSONL lines.
• On LLM end/error: chunkCount, firstChunkAt, lastChunkAt, streamDurationMs, streamedCharCount.
• capture: "metadata-only" does not store raw token text.
• capture: "preview" may include bounded streamPreview via maxStreamPreviewChars.
• With persist: true, streaming metadata is written on the LLM step at completion (deferred write for streaming LLM steps).

Streaming metadata is for local inspection and timing — not replay or cassette playback.

Correlation inside inspectRun

When the callback runs inside inspectRun / maybeInspectRun, correlation fields from getCurrentCorrelationMetadata() attach to LLM lifecycle events.

Options reference

Full API: API.md §9.

Example

examples/08-langchain-adapter

LangGraph boundary

LangGraph support rides through this same @agent-inspect/langchain callback boundary first. The v2.3 fixtures cover graph/node identity, subgraphs, checkpoint/session IDs, stream modes, handoffs, and parallel branch hints without adding a separate package. A dedicated LangGraph package remains deferred until fixtures prove that LangGraph exposes important lifecycle data unavailable through LangChain callbacks.

Future LangGraph examples must keep the same safety defaults: explicit callback installation, metadata-only capture, no raw prompt/output/tool payload capture by default, no hosted sink, and local persistence only when persist: true is set.

Runnable local recipe: langgraph-callback-local.

Decision note: LANGGRAPH-ADAPTER-BOUNDARY.md.

TUI (@agent-inspect/tui)

Status: experimental programmatic API; CLI integration is the intended usage.

npm install agent-inspect @agent-inspect/tui
npx agent-inspect view <run-id> --tui

Requires an interactive terminal. See API.md §10.

Vitest (@agent-inspect/vitest)

Status: experimental reporter package — optional package published in the aligned v2.2.0 package set.

npm install agent-inspect @agent-inspect/vitest vitest

The reporter creates safe, structural artifacts for failed tests that explicitly attach AgentInspect trace metadata. It never guesses trace files by timestamp and does not read trace contents into artifacts.

import { createAgentInspectVitestReporter } from "@agent-inspect/vitest";

export default {
  test: {
    reporters: [
      "default",
      createAgentInspectVitestReporter({
        artifactDir: ".agent-inspect/vitest-artifacts",
        retainSuccessful: 5,
      }),
    ],
  },
};

Attach explicit metadata from the test harness, or provide resolveTrace(test):

test("agent workflow", async (ctx) => {
  ctx.task.meta.agentInspect = {
    runId: "support-agent",
    tracePath: ".agent-inspect/support-agent.jsonl",
    artifactLabel: "support-agent",
  };
});

• Explicit association only — no timestamp matching or directory guessing.
• Failure artifacts by default — passing-test artifacts are kept only when retainSuccessful is configured.
• Bounded success retention — successful artifacts are capped by maxSuccessfulTraces.
• Failure-preserving — reporter/artifact errors are surfaced through diagnostics and do not replace original Vitest failures.
• Local-only — no network I/O, no hosted upload, no GitHub API, and no root/core Vitest dependency.
• Safe rendering — artifacts include structural test/run/file references only, not raw trace contents, prompts, outputs, request/response bodies, headers, API keys, secrets, or tool payloads.

Full API: API.md §12.

Jest (@agent-inspect/jest)

Status: experimental reporter package — optional package published in the aligned v2.2.0 package set.

npm install agent-inspect @agent-inspect/jest jest

The reporter creates safe, structural artifacts for failed Jest assertions that explicitly attach AgentInspect trace metadata through a map or resolver. It never guesses trace files by timestamp and does not read trace contents into artifacts.

module.exports = {
  reporters: [
    "default",
    [
      "@agent-inspect/jest",
      {
        artifactDir: ".agent-inspect/jest-artifacts",
        retainSuccessful: 5,
        associations: {
          "agent.test.cjs::agent suite agent workflow": {
            runId: "support-agent",
            tracePath: ".agent-inspect/support-agent.jsonl",
          },
        },
      },
    ],
  ],
};

• Explicit association only — use associations or resolveTrace(test); no timestamp matching or directory guessing.
• Jest lifecycle — processes assertion results from onTestResult and aggregated file results from onRunComplete.
• Failure artifacts by default — passing-test artifacts are kept only when retainSuccessful is configured.
• Bounded success retention — successful artifacts are capped by maxSuccessfulTraces.
• Failure-preserving — reporter/artifact errors are surfaced through diagnostics and do not replace original Jest failures.
• Local-only — no network I/O, no hosted upload, no GitHub API, and no root/core Jest dependency.
• Safe rendering — artifacts include structural test/run/file references only, not raw trace contents, prompts, outputs, request/response bodies, headers, API keys, secrets, or tool payloads.

Full API: API.md §13.

OpenAI Agents JS (@agent-inspect/openai-agents)

Local-only guide: OPENAI-AGENTS-LOCAL.md

Status: experimental adapter — optional package published in the aligned v2.2.0 package set.

The safe integration boundary is documented in OPENAI-AGENTS-JS-TRACING.md. Install the AgentInspect processor by replacing processors:

import { setTraceProcessors } from "@openai/agents";
import { agentInspectProcessor } from "@agent-inspect/openai-agents";

setTraceProcessors([
  agentInspectProcessor({
    traceDir: "./.agent-inspect",
    capture: "metadata-only",
  }),
]);

Do not use addTraceProcessor() as the default AgentInspect path; that preserves the OpenAI default exporter in server runtimes. The processor does not auto-install itself, does not upload, and does not add OpenAI Agents dependencies to root/core.

Integration modes:

• Local-only replacement: setTraceProcessors([agentInspectProcessor(...)]) replaces existing processors for the current process. This is the documented safe default when you want AgentInspect to own local trace output and avoid preserving the SDK default exporter.

• Additional processor: addTraceProcessor(agentInspectProcessor(...)) is an advanced, user-owned choice. It can preserve existing/default processors and any backend export behavior they already perform; use it only when that is intentional.

• No auto-install — importing or constructing agentInspectProcessor() never calls setTraceProcessors() or addTraceProcessor().

• No upload behavior — the processor writes only to an explicit local writer or traceDir.

• Metadata-only by default — records trace/span IDs, parentage, names, timing, status, errors, safe model/tool names, token counts, and bounded summaries.

• No raw payload capture by default — prompts, messages, generated text, function inputs/outputs, arbitrary custom data, trace exporter credentials, headers, request bodies, response bodies, and hosted tool payloads are not persisted.

• Preview capture is not enabled yet — capture: "preview", redactionProfile, and maxPreviewChars are diagnosed through getDiagnostics() and do not persist raw previews.

• Fixture-backed lifecycle coverage — local tests and the recipe cover agent, generation, function tool, handoff, guardrail, response, MCP tools, custom, transcription, and speech span shapes without provider calls.

Full API: API.md §14.

Runnable local recipe: openai-agents-local-tracing.

Demand-gated framework decisions

Mastra

v2.3 decision: no official package, recipe, or conformance fixture.

The v2.3 evidence review found no open adapter request and no verified extension point in this repository that would produce useful local AgentInspect traces without hidden framework patching or new root/core dependencies. A future Mastra path must first prove:

• explicit user demand, such as an issue, design-partner request, or retained external recipe;
• a stable, framework-native callback/export hook;
• metadata-only local trace output with no hosted upload or provider calls by default;
• no dependency leakage into agent-inspect root or @agent-inspect/core;
• no raw prompt, output, tool payload, header, or request/response capture by default.

Until those are true, Mastra stays outside the official adapter set rather than shipping a shallow package.

NestJS

v2.3 decision: no official framework adapter package.

NestJS remains covered through structured-log ingestion, not app bootstrap wrapping. The supported recipe is examples/recipes/nestjs-json-logging, which maps Nest-shaped JSON lines into local execution trees without importing @nestjs/*, starting an HTTP server, or changing application behavior.

A future Nest helper remains demand-gated and must be narrower than a framework adapter. Acceptable evidence would be a repeated need to reduce logging/harness setup friction while preserving explicit opt-in, local-only output, and zero root/core Nest dependency. Broad interceptors, automatic module scanning, monkey-patching, request body capture, or default telemetry upload remain out of scope.

MCP client telemetry (@agent-inspect/mcp)

Status: experimental optional package — v2.4.0 train.

@agent-inspect/mcp traces MCP client tools/list and tools/call as local AgentInspect tool steps. It records server identity (name + URL hash), tool name, bounded argument/result summaries, duration, errors, and optional session metadata (sessionId, toolCallId, mcpToolCallId).

Install

npm install agent-inspect @agent-inspect/mcp

Wrap a client

import { inspectRun } from "agent-inspect";
import { wrapMcpClient } from "@agent-inspect/mcp";

const traced = wrapMcpClient(mcpClient, {
  serverName: "docs-server",
  serverUrl: process.env.MCP_SERVER_URL,
  sessionId: "sess-123",
});

await inspectRun("support-agent", async () => {
  await traced.listTools?.();
  await traced.callTool({ name: "search", arguments: { query: "refund policy" } });
});

wrapMcpClient accepts any object matching the documented McpClientLike shape. It does not require @modelcontextprotocol/sdk at runtime.

Boundaries (v2.4)

Recipe: examples/recipes/mcp-client-tracing.

Session navigation for multi-run workflows uses agent-inspect sessions / session and optional search --session / check --session — see CLI.md and SESSIONS-AND-WORKFLOW-CAUSALITY.md.

Local viewer (@agent-inspect/viewer)

Status: optional package — v2.6.0 train.

Read-only localhost HTTP server for browsing traces on disk. Wired through agent-inspect serve.

npm install agent-inspect @agent-inspect/viewer
npx agent-inspect serve --dir ./.agent-inspect-runs

Read-only MCP server (@agent-inspect/mcp-server)

Status: optional package — v2.6.0 train.

Stdio MCP server exposing read-only tools (list_traces, read_trace, search_traces, find_first_error, find_slowest_path, compare_runs, run_checks, create_share_safe_report). Distinct from @agent-inspect/mcp (client telemetry).

import { runReadOnlyMcpServer } from "@agent-inspect/mcp-server";

await runReadOnlyMcpServer({ redactionProfile: "share" });

Recipe: examples/recipes/read-only-mcp-server. VS Code: VSCODE.md.

Future adapters (not shipped)

Direction only — see ROADMAP.md:

• NestJS helper patterns — only if demand proves a narrow harness/bootstrap helper is worth maintaining beyond LOGGING-PLAYBOOK.md and the current NestJS logging recipe.
• Mastra — deferred until demand and extension-point evidence justify a narrow explicit integration.

No automatic universal instrumentation. Integrations remain explicit and opt-in.

Related docs

• API.md — adapter options and stability policy
• ADAPTER-CONFORMANCE.md — no-network fixture matrix and shared expectations
• SAFE-TRACE-SHARING.md — review exports before sharing
• LIMITATIONS.md — LangChain streaming and metadata boundaries