retrace-sdk

The execution replay engine for AI agents. Record, replay, fork & share AI agent executions — TypeScript SDK.

Installation

npm install retrace-sdk

Requires Node.js 20+. ESM-only package.

Quick Start

import { configure, trace } from "retrace-sdk";

configure({ apiKey: "rt_..." }); // Get your key at retraceai.tech/settings

const myAgent = trace(async (prompt: string) => {
  const response = await openai.chat.completions.create({
    model: "gpt-5.5",
    messages: [{ role: "user", content: prompt }],
  });
  return response.choices[0].message.content;
}, { name: "my-agent" });

await myAgent("What is quantum computing?");

Auto-Instrumentation

LLM calls from all major providers are captured automatically:

• OpenAI — openai.chat.completions.create() captured
• Anthropic — anthropic.messages.create() captured
• Google Gemini — ai.models.generateContent() captured

No extra setup needed. Install the provider SDK alongside retrace-sdk.

Configuration

import { configure } from "retrace-sdk";

configure({
  apiKey: "rt_...",           // or RETRACE_API_KEY env var
  baseUrl: "https://api.retraceai.tech",
  projectId: "...",                 // or RETRACE_PROJECT_ID env var
});

Set RETRACE_ENABLED=false to disable recording without changing code.

Manual Span Creation

import { record, SpanType } from "retrace-sdk";

const recorder = record({ name: "custom-agent" });
recorder.start();

const span = recorder.startSpan("web-search", SpanType.TOOL_CALL, { query: "latest news" });
// ... do work ...
recorder.endSpan(span, { results: ["..."] });

recorder.end("Done");

Resumable Execution (Cascade Replay)

Mark a function as resumable to enable full cascade replay from the dashboard:

import { configure, trace } from "retrace-sdk";

configure({ apiKey: "rt_..." });

const myAgent = trace(async (prompt: string) => {
  const plan = await planner(prompt);
  const result = await executor(plan);
  return summarize(result);
}, { name: "my-agent", resumable: true });

When you fork at any span in the dashboard, the SDK re-executes the entire function with modified input — not just one LLM call.

Error Handling

import { RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceRateLimitError, RetraceEnforcementError } from "retrace-sdk";

Typed errors for auth failures, credit exhaustion, and rate limiting.

Enforcement (Circuit Breakers)

Hard ceilings that stop a runaway agent before the next call. Local limits are enforced offline (zero network); serverEnforcement: true also consults centrally-managed server policies.

import { configure, RetraceEnforcementError } from "retrace-sdk";

configure({
  apiKey: "rt_...",
  maxStepsPerRun: 50,
  maxUsdPerRun: 2.0,
  serverEnforcement: true, // optional: also consult server policies
});

try {
  await runAgent("...");
} catch (e) {
  if (e instanceof RetraceEnforcementError) console.log(e.verdict, e.reason);
}

Precedence: explicit arg > env var (RETRACE_MAX_STEPS_PER_RUN, RETRACE_MAX_TOKENS_PER_RUN, RETRACE_MAX_USD_PER_RUN, RETRACE_SERVER_ENFORCEMENT) > unset. If the server check is unreachable, local limits still apply.

Multi-Agent Context

Tag spans with an agent id/role so the dashboard can draw the agent topology and run inter-agent detectors:

import { withAgent } from "retrace-sdk";

await withAgent({ id: "planner", role: "planner" }, async () => {
  await callPlanner(prompt);
});

Golden Cassettes (CI Regression Gates)

Record a run as a golden cassette and gate on it offline in CI with retrace ci replay:

import { writeGoldenCassette } from "retrace-sdk";

writeGoldenCassette("golden.json", { recorder });

Sampling

configure({ apiKey: "rt_...", sampleRate: 0.1 }); // Record 10% of traces

Changelog

0.13.0

• Multi-agent context — withAgent({ id, role }) tags spans for topology + inter-agent detectors

• Golden cassettes — writeGoldenCassette(path, { recorder }) records a run as a CI regression fixture

• Pre-call enforcement gate — local step/token/USD-per-run ceilings enforced offline; RetraceEnforcementError thrown instead of silently skipping the call

• Sessions — sessionId option in TraceRecorder and trace() to group multi-turn conversations

• Multi-Agent — setAgentId() on SpanBuilder for cross-agent tracing

• Guardrail support — SDK respects HALT commands from server-side guardrail policies

0.2.2

• Fixed — OpenAI interceptor no longer creates dummy client instance to find prototype

0.6.0

• Token ID capture — Stores output token IDs + logprobs from OpenAI responses (enables speculative decoding during replay)
• SpanData extended — New token_ids and logprobs fields on SpanData interface
• Shared schema — SpanInputSchema updated with token_ids and logprobs optional arrays

0.2.1

• Offline buffer — stores up to 1000 messages when WebSocket disconnects, flushes on reconnect
• HTTP retry — 3 attempts with exponential backoff on fallback transport
• Cascade replay — resumable: true option registers function for SDK-level re-execution
• Resume listener — handles server 'resume' commands for fork replay

0.2.0

• Typed errors (RetraceAuthError, RetraceCreditsExhaustedError, RetraceRateLimitError)
• Trace sampling via sampleRate config
• Auto-instrumentation for OpenAI, Anthropic, Gemini
• WebSocket + HTTP fallback transport

Links

• Documentation
• GitHub
• npm