rollout
Sign up free

Getting started

Quickstart — TypeScript

From a clean Node project to a verified trace in your workspace in a few minutes. This is the TypeScript counterpart to the Python quickstart — same model, same workspace.

1. Install

The base package pulls in no provider SDKs. Requires Node 20+.

shell
pnpm add @mv37/rollout

If you instrument a provider, add it as an optional peer where you need it — for example the OpenAI SDK or the Vercel AI SDK:

shell
pnpm add @mv37/rollout openaipnpm add @mv37/rollout ai          # Vercel AI SDK

2. Get an API key

Create a project in your Rollout workspace and copy its API key. The SDK reads ROLLOUT_API_KEY from the environment by default:

shell
export ROLLOUT_API_KEY="rl_..."export ROLLOUT_ENVIRONMENT="production"   # optional

Heads up

The TypeScript SDK is server-side. Never expose a Rollout workspace API key in a browser bundle — instrument from a route handler or edge function instead.

3. Initialize a client

Create a Rollout client and pass it around, or call rollout.init() once for a global client the module-level helpers route through. Both read the same options from arguments or the environment.

setup.ts
import { Rollout } from "@mv37/rollout";// explicit clientconst rollout = new Rollout({ agentName: "support_agent", environment: "production" });// — or — one global client for the whole processimport * as rolloutMod from "@mv37/rollout";rolloutMod.init({ agentName: "support_agent", environment: "production" });

4. Send your first trace

A trace is one agent run. Open it with a callback, record the conversation with trace.message(...), wrap model calls in a span, and record usage. The trace flushes when you shut down.

first-trace.ts
import { Rollout } from "@mv37/rollout";const rollout = new Rollout({ agentName: "support_agent" });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.message({ role: "assistant", content: "Your order has shipped." });  trace.feedback("thumbs_up", true);});await rollout.shutdown();

5. 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:

verify.ts
const result = await rollout.check();console.log(result.ok, result.message);

Next steps