agent-trace-kit

agent-trace-kit records heterogeneous agent events into one deterministic timeline, then helps replay and diff runs.

Features

• Normalizes MCP, A2A, AG-UI, tool, and app events
• Deterministically sorts concurrent events using timestamp, sequence, and source identity
• Groups events by span and reconstructs parent-child trees
• Diffs two runs and points to the first divergence

Usage

import { TraceRecorder, diffTraces } from "agent-trace-kit";

const recorder = new TraceRecorder();
recorder.add({
  protocol: "mcp",
  source: "server",
  kind: "tool_call",
  timestamp: "2026-04-01T10:00:00.000Z",
  runId: "run-1",
  spanId: "span-1",
  payload: { tool: "lookup", args: { symbol: "BTC" } }
});

const trace = recorder.finalize();
const diff = diffTraces(trace, trace);
console.log(diff.status);