智能代理调试

Install

Current npm release: 1.2.0.

npm install agent-inspect

pnpm add agent-inspect

Verify the CLI is available:

npx agent-inspect --help

For a clean npm/pnpm install checklist with ESM, CJS, and CLI checks, see Clean install smoke test.

60-second quickstart

Create demo.mjs:

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

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

await inspectRun(
  "support-agent",
  async () => {
    const plan = await step("plan", async () => {
      await delay(40);
      return { intent: "refund-policy", needsPolicy: true };
    });

    const policy = await step.tool("retrieve-policy", async () => {
      await delay(60);
      return { text: "Refunds are available within 30 days of purchase." };
    });

    return step.llm("generate-answer", async () => {
      await delay(80);
      return `Policy: ${policy.text} (intent: ${plan.intent})`;
    });
  },
  { traceDir: "./.agent-inspect" }
);

Run it, then inspect the trace:

node demo.mjs
npx agent-inspect list --dir ./.agent-inspect
npx agent-inspect view <run-id> --dir ./.agent-inspect
npx agent-inspect view <run-id> --dir ./.agent-inspect --summary

Full flow:

npm install agent-inspect
node demo.mjs
npx agent-inspect list --dir ./.agent-inspect

Simplified example output (actual CLI formatting may differ slightly):

support-agent
✔ plan
✔ tool:retrieve-policy
✔ llm:generate-answer

A runnable copy lives in examples/00-quickstart-demo.

Env-gated tracing (eval harnesses, CI): use maybeInspectRun and set AGENT_INSPECT=1 when you want a trace — otherwise no files are written.

import { maybeInspectRun } from "agent-inspect";

await maybeInspectRun("eval-case-42", async () => runAgent());

AGENT_INSPECT=1 node eval-runner.mjs

Examples and recipes

Recipes are deterministic and require no external services by default. Index: examples/README.md, examples/recipes/README.md.

Optional packages

CLI at a glance

Full flags and behavior: docs/CLI.md.

Real-world workflows

• Debug a failed tool call or thrown error in a support or ops agent.
• See which step dominated latency in a multi-step planner or RAG pipeline.
• Diff two runs after a prompt, model, or routing change (see diff examples).
• Point logs / tail at existing job or service logs to get a local execution view without shipping data upstream.
• Export a run to Markdown for a PR, postmortem, or internal thread — then review before sharing.
• Keep traces on disk while still using enterprise observability elsewhere.

agent-inspect comparison

It can complement LangSmith, Langfuse, Braintrust, Phoenix/OpenInference, OpenTelemetry, New Relic, Datadog, and similar platforms — but it does not replace their production or eval workflows.

For a detailed comparison, see Compare with other tools.