Beta
The package is published as @mv37/rollout and requires Node 20+. The public API is in beta; expect additive changes. Never expose a Rollout workspace API key in a browser bundle — the SDK is server-side.
Install
The base install depends on no provider SDKs. Provider SDKs are optional peers — install them in the app or example that needs them:
pnpm add @mv37/rollout# add a provider peer where you need itpnpm add @mv37/rollout openaipnpm add @mv37/rollout ai # Vercel AI SDKWhat's implemented
Implemented today: core observability events, traces, spans, messages, tools, feedback, signals, identity, Node batching, edge mode, disabled browser mode, Vercel AI SDK wrapping, sampling, redaction, diagnostics, and lifecycle methods.
Not yet implemented: pulling datasets, starting hosted benchmark runs, executing benchmark verifier harnesses, or a generic rollout.wrap() for arbitrary providers. For the OpenAI JS SDK, use manual spans; for optimization, use the fetch-handler target.
Basic usage
Create a Rollout client and open a trace. Inside it, record messages and wrap model calls in spans; the trace flushes when you shut down.
import { Rollout } from "@mv37/rollout";const rollout = new Rollout({ apiKey: process.env.ROLLOUT_API_KEY, agentName: "support_agent", environment: "production",});await rollout.trace("support_agent", async (trace) => { trace.message({ role: "user", content: "Where is my order?" }); await trace.span("llm", async (span) => { span.recordInput({ messages: [{ role: "user", content: "Where is my order?" }] }); span.recordOutput({ content: "Your order has shipped." }); span.setUsage({ input_tokens: 120, output_tokens: 24 }); }, { name: "model.call", model: "gpt-4.1-mini", provider: "openai" }); trace.feedback("thumbs_up", true);});await rollout.shutdown();Module-level convenience
If you prefer not to pass a client around, call rollout.init() once and use the module-level helpers — they route through the client it creates.
import * as rollout from "@mv37/rollout";rollout.init({ apiKey: process.env.ROLLOUT_API_KEY, agentName: "support_agent",});const runAgent = rollout.agent("support_agent", async (message: string) => { return `Echo: ${message}`;});await runAgent("hello");await rollout.shutdown();Verify the connection
check() sends a short completed diagnostic trace through POST /v1/events:batch — the fastest way to confirm your key and base URL work:
const result = await rollout.check();console.log(result.ok, result.message);Explore
generateText / streamText and more.Manual provider spansInstrument the OpenAI JS SDK with explicit llm and tool spans.Edge & browserRequest-scoped runtimes and flush(); browser mode is disabled by default.ConfigurationConstructor options, env vars, and the scrubber / beforeSend pipeline.Optimization targetsOptimize a TypeScript agent over HTTP with a fetch-handler target.