Vercel AI SDK - Raindrop

The @raindrop-ai/ai-sdk package provides automatic instrumentation for the Vercel AI SDK. It captures events and traces with zero configuration required at each call site. Why use this over the OTEL-based integration?

No OpenTelemetry setup required
Works in Node.js out of the box
Dedicated browser/edge entrypoint without async_hooks shims
Works in Cloudflare Workers when nodejs_compat is enabled (see “Cloudflare Workers” below)
Automatic tool call tracing
Built-in attachment support
User trait identification
Instrumented signal tracking

Installation

npm install @raindrop-ai/ai-sdk

yarn add @raindrop-ai/ai-sdk

pnpm add @raindrop-ai/ai-sdk

bun add @raindrop-ai/ai-sdk

Quick Start

import * as ai from "ai";
import { openai } from "@ai-sdk/openai";
import { createRaindropAISDK, eventMetadata } from "@raindrop-ai/ai-sdk";

// 1. Create the Raindrop client
const raindrop = createRaindropAISDK({
  writeKey: process.env.RAINDROP_WRITE_KEY!,
});

// 2. Wrap the AI SDK with defaults
const { generateText, streamText } = raindrop.wrap(ai, {
  context: {
    userId: "user_123",
    eventName: "chat",
  },
});

// 3. Use as normal - events and traces are captured automatically
const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "Hello, world!",
  // Optional: override wrap defaults for this call
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({
      userId: "user_456",
      convoId: "chat_123",
      eventName: "support-chat",
      properties: { source: "web" },
    }),
  },
});

// Optional: identify user traits
await raindrop.users.identify({
  userId: "user_123",
  traits: { plan: "pro" },
});

// 4. Flush before shutdown (serverless/scripts)
await raindrop.flush();

That’s it. Every generateText, streamText, generateObject, and streamObject call is now tracked.

Native Telemetry Integration (AI SDK v7+)

AI SDK v7 introduced a pluggable TelemetryIntegration interface. Raindrop provides a native implementation that replaces Proxy-based wrapping with first-class SDK integration. Requires AI SDK v7 or later — using nativeTelemetry with v6 or earlier will throw an error.

Quick start: `registerTelemetry(raindrop())`

The simplest v7 setup is the raindrop() factory, which returns a ready-to-register telemetry integration. The writeKey defaults to process.env.RAINDROP_WRITE_KEY:

import { generateText, registerTelemetry } from "ai";
import { raindrop } from "@raindrop-ai/ai-sdk";

registerTelemetry(raindrop());

const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "Hello!",
  telemetry: { functionId: "chat" }, // no `isEnabled` needed in v7
});

raindrop() is self-contained — no @ai-sdk/otel or OpenTelemetry setup is required. Pass context and subagentWrapping to customise behaviour, e.g. raindrop({ context: { userId: "user_123", eventName: "chat" } }). The returned integration also exposes flush() / shutdown() so short-lived scripts and serverless handlers can drain buffered telemetry before exiting.

Using `wrap()` with native telemetry

Enable the native path by passing nativeTelemetry: true:

import * as ai from "ai";
import { createRaindropAISDK } from "@raindrop-ai/ai-sdk";

const raindrop = createRaindropAISDK({ writeKey: process.env.RAINDROP_WRITE_KEY! });
const { generateText, streamText } = raindrop.wrap(ai, {
  context: { userId: "user_123", eventName: "chat" },
  nativeTelemetry: true, // uses SDK's TelemetryIntegration instead of Proxy
});

Without nativeTelemetry, wrap() uses the existing Proxy-based wrapping, which works across all AI SDK versions (v4+).

Direct registration (without `wrap()`)

You can also register the integration directly with the AI SDK’s global registry:

import { registerTelemetry } from "ai";
import { createRaindropAISDK } from "@raindrop-ai/ai-sdk";

const raindrop = createRaindropAISDK({ writeKey: process.env.RAINDROP_WRITE_KEY! });

// Create and register the integration globally
registerTelemetry(
  raindrop.createTelemetryIntegration({ userId: "user_123", eventName: "chat" })
);

// Use the AI SDK directly — no wrapping needed
const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "Hello!",
  experimental_telemetry: { isEnabled: true },
});

On AI SDK v7 betas before beta.111 this function was named registerTelemetryIntegration. It was renamed to registerTelemetry in the v7 canary line — use registerTelemetry on current v7.

You can also pass the integration per-call via experimental_telemetry.integrations if you need different configuration per request.

When to use native telemetry vs. default wrapping

The native integration uses the AI SDK’s own callback system instead of intercepting function calls. This is a cleaner integration, but some features from the default wrap() path are not yet available:

Feature	Default (`wrap()`)	Native (`nativeTelemetry: true`)
Events and traces	Yes	Yes
Tool call tracing	Yes	Yes
`buildEvent` callback	Yes	Not yet supported
Automatic attachment extraction	Yes	Not yet supported
Self-diagnostics	Yes	Yes

Use nativeTelemetry: true if you want a cleaner integration without Proxy wrapping and don’t need buildEvent or attachment features. Use the default (no flag) if you rely on those features or want the most complete telemetry today.

Runtime support

Browsers and edge runtimes

Use the browser entrypoint:

import { createRaindropAISDK } from "@raindrop-ai/ai-sdk/browser";

The SDK works without async_hooks shims. When AsyncLocalStorage is not available, Raindrop falls back to synchronous context scoping: nested work in the same call stack still inherits context, but automatic propagation across arbitrary async boundaries is not guaranteed. If you need stable correlation across async hops or multiple requests, pass an explicit eventId with eventMetadata().

Node.js (recommended)

Use the default import:

import { createRaindropAISDK } from "@raindrop-ai/ai-sdk";

In Node, the default entrypoint wires up AsyncLocalStorage automatically.

Cloudflare Workers

Cloudflare Workers supports a subset of Node’s AsyncLocalStorage when you enable nodejs_compat (docs). If nodejs_compat is enabled, import the Workers entrypoint:

import { createRaindropAISDK } from "@raindrop-ai/ai-sdk/workers";

This enables real AsyncLocalStorage propagation in Workers. If nodejs_compat is not enabled, use the browser entrypoint instead. The SDK still works, but it uses the same synchronous fallback described above rather than real AsyncLocalStorage.

Configuration

Client Options

const raindrop = createRaindropAISDK({
  writeKey: "your-write-key",        // Required
  endpoint: "https://api.raindrop.ai/v1",  // Optional, defaults to production
  projectId: "support-prod",         // Optional: route events to a specific project (slug)

  traces: {
    enabled: true,                   // Default: true
    flushIntervalMs: 1000,           // Default: 1000
    maxBatchSize: 50,                // Default: 50
    debug: false,                    // Logs trace shipping
    debugSpans: false,               // Logs span parent relationships

    // Optional: inspect, rewrite, or drop OTLP spans before they ship.
    // Return a new span, `null` to drop, or `undefined` to keep as-is.
    // Throws are treated as drops (fail-closed).
    transformSpan: (span) => span,

    // By default, credential-shaped property names (apiKey, secretAccessKey,
    // privateKey, sessionToken, ...) inside ai.request.providerOptions and
    // ai.response.providerMetadata are replaced with "[REDACTED]". Set true
    // to ship those JSON blobs verbatim.
    disableDefaultRedaction: false,
  },

  events: {
    enabled: true,                   // Default: true
    partialFlushMs: 1000,            // Debounce for streaming updates
    debug: false,                    // Logs event shipping
  },
});

Wrap Options

const { generateText } = raindrop.wrap(ai, {
  // Set defaults at wrap-time. Override per call with eventMetadata().
  context: {
    userId: "user_123",              // Default user context
    eventId: "evt_abc",              // Optional - use your own ID for correlation
    eventName: "chat",               // Optional - categorize events
    convoId: "convo_xyz",            // Optional - group events into conversations
    properties: { tier: "pro" },     // Optional - custom metadata
    featureFlags: ["prompt-v2"],     // Optional - active feature flags / experiment variants
    attachments: [],                 // Optional - input/output attachments
  },

  autoAttachment: true,               // Default: true. Set false to disable automatic parsing

  // Optional: customize event payload from messages
  buildEvent: (messages) => ({
    input: messages.filter(m => m.role === "user").map(m => m.content).join("\n"),
    output: messages.filter(m => m.role === "assistant").pop()?.content,
    properties: { messageCount: messages.length },
  }),

  // Optional: inject an internal self diagnostics tool for agent flows
  selfDiagnostics: {
    enabled: false, // Default: false
    toolName: "__raindrop_report", // Optional, default shown
    guidance: "Optional extra guidance for your domain", // Optional
    // Default signals (used when `signals` is omitted):
    signals: {
      missing_context: {
        description:
          "You cannot complete the task because critical information, credentials, or access is missing and the user cannot provide it. " +
          "Do NOT report this for normal clarifying questions — only when you are blocked.",
        sentiment: "NEGATIVE",
      },
      repeatedly_broken_tool: {
        description:
          "A tool has failed or not returned the expected response on multiple distinct attempts in this conversation, preventing task completion. " +
          "A single tool error is NOT enough — the tool must be persistently broken or aberrantly behaving across retries.",
        sentiment: "NEGATIVE",
      },
      capability_gap: {
        description:
          "The task requires a tool, permission, or capability that you do not have. " +
          "For example, the user asks you to perform an action but no suitable tool exists, or you lack the necessary access. " +
          "Do NOT report this if you simply need more information from the user — only when the gap is in your own capabilities.",
        sentiment: "NEGATIVE",
      },
      complete_task_failure: {
        description:
          "You were unable to accomplish what the user asked despite making genuine attempts. This might be things like, you genuinely do not have the capabilities the user is asking for. You have tried but run into a persistent bug in the environment etc. " +
          "This is NOT a refusal or policy block — you tried and failed to deliver the result.",
        sentiment: "NEGATIVE",
      },
    },
  },

  // Optional: control what gets sent
  send: {
    events: true,   // Default: true
    traces: true,   // Default: true
  },
});

Projects

Route events to a specific project by passing its slug as projectId:

const raindrop = createRaindropAISDK({
  writeKey: "your-write-key",
  projectId: "support-prod",
});

This sets the X-Raindrop-Project-Id header on every outbound event. Omit it (or pass "default") to use your org’s default Production project, which is the existing behavior. Single-project orgs need nothing new.

Multiple projects in one process

To report to different projects from one process, create one Raindrop client per project and use its per-instance wrap() lanes. Each wrapped generateText/streamText ships under that client’s own writeKey and X-Raindrop-Project-Id, so the projects stay isolated:

import * as ai from "ai";
import { createRaindropAISDK } from "@raindrop-ai/ai-sdk";

const rdSupport = createRaindropAISDK({ writeKey: KEY, projectId: "support-prod" });
const rdBilling = createRaindropAISDK({ writeKey: KEY, projectId: "billing-prod" });

const support = rdSupport.wrap(ai); // spans -> support-prod
const billing = rdBilling.wrap(ai); // spans -> billing-prod

The AI SDK v7 global telemetry registry (registerTelemetry(raindrop())) is not per-project. registerTelemetry fans every call out to every registered integration, so registering two clients globally duplicates all traffic to both projects — each copy shipped under its own writeKey/X-Raindrop-Project-Id (this is duplication, not cross-project leakage). For per-project isolation, use the per-instance client.wrap(ai) lanes shown above rather than registering more than one integration globally.

Mixed processes (a tracing-enabled raindrop-ai client alongside this integration). If the same process also constructs a tracing-enabled raindrop-ai js-sdk client, its Traceloop pipeline auto-instruments the underlying LLM libraries process-wide — so calls made through this integration package additionally produce auto-instrumented spans that route to the js-sdk pipeline owner’s project. This is pre-existing behavior, unrelated to per-instance routing. Run mixed setups with a single project, or scope the integration’s calls with the js-sdk client’s asCurrent().

Context & Metadata

Per-Call Context Override (Recommended)

Set stable defaults in wrap() and override them per call with eventMetadata() when needed:

import { createRaindropAISDK, eventMetadata } from "@raindrop-ai/ai-sdk";

// Wrap once with defaults
const { generateText } = raindrop.wrap(ai, {
  context: {
    userId: "default-user",
    eventName: "chat",
    properties: { app: "web" },
  },
});

// Override defaults for this call
const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "Hello!",
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({
      userId: "specific-user",       // Required per call
      convoId: "convo-123",          // Conversation routing
      eventName: "support-chat",     // Event categorization
      properties: { source: "web" }, // Additional metadata
      // eventId: "evt_123",         // Optional explicit eventId for correlation
    }),
  },
});

This keeps common values in one place while allowing each request to set or override userId, convoId, eventName, properties, or eventId. Merge behavior:

Call-time values override wrap-time defaults
properties are merged (call-time wins on conflicts)
featureFlags are merged the same way (call-time wins per flag)
eventId is auto-generated if neither wrap-time nor call-time sets it

If you need full manual control over attachments, set autoAttachment: false in wrap().

context in wrap() is optional but useful for defaults. If both are present, call-time eventMetadata() wins.

const { generateText } = raindrop.wrap(ai, {
  context: { userId: "unknown" }, // Fallback only
});

// Preferred: set the real userId per call
await generateText({
  model,
  prompt,
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({ userId: actualUserId }),
  },
});

Feature Flags

Record which feature flags and experiment variants were active for each generation, so you can compare AI quality across variants in Raindrop. Flags are sent as feature_flags on the event. Two input forms are accepted: an array of flag names (each implicitly "true") or an object with explicit values (string, number, or boolean — all stringified before sending). ["prompt-v2"] ships as {"prompt-v2": "true"}; { "max-retries": 3, reasoning: false } ships as {"max-retries": "3", "reasoning": "false"}. Set flags that apply to every call at wrap-time, and per-request variants with eventMetadata():

// Flags that are stable for this deployment / wrapper
const { generateText } = raindrop.wrap(ai, {
  context: {
    userId: "user_123",
    eventName: "support-chat",
    featureFlags: ["prompt-v2"], // applies to every call through this wrapper
  },
});

// Per-request: flag values you resolved for this user from your flag
// provider (LaunchDarkly, Statsig, PostHog, ...)
const retrievalStrategy = await flagProvider.getVariant("retrieval-strategy", userId); // "bm25" | "hybrid"

const result = await generateText({
  model: openai("gpt-4o"),
  prompt: question,
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({
      userId,
      // Merged over wrap-time flags — call-time wins per flag
      featureFlags: { "retrieval-strategy": retrievalStrategy },
    }),
  },
});

The example above ships {"prompt-v2": "true", "retrieval-strategy": "hybrid"}. To add flags to an event that has already been created — for example, after a fallback decision made once the generation finished — use events.setFeatureFlags() with the event’s ID:

await raindrop.events.setFeatureFlags(eventId, { "fallback-model": "gpt-4o-mini" });

Feature flags work on both integration paths: the default Proxy wrap() (AI SDK v4+) and native telemetry on v7+ (nativeTelemetry: true, raindrop({ context: { featureFlags: [...] } }), or createTelemetryIntegration({ featureFlags: [...] })).

AI SDK UI / useChat with client-side tools

When you use AI SDK UI (useChat) with client-side tools, one user turn can produce multiple POST requests to your route handler. This commonly happens when you use:

sendAutomaticallyWhen
onToolCall
addToolOutput
user approval / confirmation flows

If you generate a new eventId on every request, Raindrop will treat each tool handoff as a separate event. Use eventMetadataFromChatRequest() in your route handler to derive stable metadata from the default AI SDK UI request body:

convoId is derived from the chat request id
eventId is derived from the latest user message in messages

This lets the wrapper keep intermediate tool-calls responses pending and patch the same logical event until the model produces a final answer.

import { openai } from "@ai-sdk/openai";
import * as ai from "ai";
import {
  createRaindropAISDK,
  eventMetadataFromChatRequest,
} from "@raindrop-ai/ai-sdk";

const raindrop = createRaindropAISDK({
  writeKey: process.env.RAINDROP_WRITE_KEY!,
});

const { streamText } = raindrop.wrap(ai, {
  context: {
    userId: "user_123",
    eventName: "chat",
  },
});

export async function POST(req: Request) {
  const body = await req.json();
  const { messages } = body as { messages: ai.UIMessage[] };

  const result = streamText({
    model: openai("gpt-4o"),
    messages: await ai.convertToModelMessages(messages),
    experimental_telemetry: {
      isEnabled: true,
      metadata: eventMetadataFromChatRequest({
        request: body,
      }),
    },
  });

  const response = result.toUIMessageStreamResponse();
  result.response.then(() => raindrop.flush());

  return response;
}

If your app sets userId per request, pass it into eventMetadataFromChatRequest({ request: body, userId }).If you customize the AI SDK UI request body and remove the default id or messages fields, either preserve them or pass explicit eventId / convoId with eventMetadata().

Identifying Users

Use users.identify to associate traits with a user.

await raindrop.users.identify({
  userId: "user_123",
  traits: {
    email: "user@example.com",
    plan: "paid", // we recommend 'free', 'paid', 'trial'
    orgId: "org_456",
  },
});

Tools

Tools are automatically wrapped and traced. No additional configuration needed:

import { tool } from "ai";
import { z } from "zod";
import { eventMetadata } from "@raindrop-ai/ai-sdk";

const weatherTool = tool({
  description: "Get current weather",
  parameters: z.object({ city: z.string() }),
  execute: async ({ city }) => {
    const data = await fetchWeather(city);
    return { temperature: data.temp, conditions: data.conditions };
  },
});

const { generateText } = raindrop.wrap(ai);

// Tool calls are traced with args and results
const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "What's the weather in Tokyo?",
  tools: { weather: weatherTool },
  maxSteps: 3,
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({
      userId: "user_123",
      eventName: "weather-chat",
    }),
  },
});

Self Diagnostics (Optional)

Self Diagnostics lets your agent proactively report its own issues — capability gaps, missing context, persistent tool failures — back to your team. It’s most valuable when an agent’s self-reflection provides signal you can’t easily get otherwise. When enabled, the SDK injects a hidden tool the agent calls silently when it hits an unrecoverable problem. Signals appear in Raindrop’s Self Diagnostics section and feed into issue discovery. The four default categories are missing_context, repeatedly_broken_tool, capability_gap, and complete_task_failure. You can replace these with your own.

const { generateText } = raindrop.wrap(ai, {
  context: { userId: "user_123", eventName: "support-agent" },
  selfDiagnostics: {
    enabled: true,
    // Default signals (used when `signals` is omitted):
    signals: {
      missing_context: {
        description:
          "You cannot complete the task because critical information, credentials, or access is missing and the user cannot provide it. " +
          "Do NOT report this for normal clarifying questions — only when you are blocked.",
        sentiment: "NEGATIVE",
      },
      repeatedly_broken_tool: {
        description:
          "A tool has failed or not returned the expected response on multiple distinct attempts in this conversation, preventing task completion. " +
          "A single tool error is NOT enough — the tool must be persistently broken or aberrantly behaving across retries.",
        sentiment: "NEGATIVE",
      },
      capability_gap: {
        description:
          "The task requires a tool, permission, or capability that you do not have. " +
          "For example, the user asks you to perform an action but no suitable tool exists, or you lack the necessary access. " +
          "Do NOT report this if you simply need more information from the user — only when the gap is in your own capabilities.",
        sentiment: "NEGATIVE",
      },
      complete_task_failure: {
        description:
          "You were unable to accomplish what the user asked despite making genuine attempts. This might be things like, you genuinely do not have the capabilities the user is asking for. You have tried but run into a persistent bug in the environment etc. " +
          "This is NOT a refusal or policy block — you tried and failed to deliver the result.",
        sentiment: "NEGATIVE",
      },
    },
  },
});

You don’t need to mention self diagnostics in your system prompt — the SDK handles the tool description automatically. When the agent calls the tool, a signal is tracked on the same eventId:

{
  "event_id": "evt_...",
  "signal_name": "self diagnostics - missing_context",
  "signal_type": "agent",
  "properties": {
    "source": "agent_reporting_tool",
    "category": "missing_context",
    "detail": "User asked to fix deployment but no access to logs or SSH credentials."
  }
}

Self diagnostics with native telemetry

Create the diagnostics tool and add it to your tools map:

import { createRaindropAISDK } from "@raindrop-ai/ai-sdk";
import { generateText, registerTelemetry } from "ai";

const raindrop = createRaindropAISDK({ writeKey: process.env.RAINDROP_WRITE_KEY! });

registerTelemetry(raindrop.createTelemetryIntegration({ userId: "user_123" }));

const diagnostics = raindrop.createSelfDiagnosticsTool();

await generateText({
  model: openai("gpt-4o"),
  prompt,
  tools: {
    [diagnostics.name]: diagnostics,
  },
  experimental_telemetry: { isEnabled: true },
});

Signals attach to the current Raindrop event automatically. To choose the event yourself, pass eventId or getEventId:

const diagnostics = raindrop.createSelfDiagnosticsTool({
  getEventId: () => currentEventId,
});

You can also pass signals, guidance, toolName, and onMissingEventId ("warn", "ignore", or "throw").

Nested LLM Calls in Tools

If your tool makes additional LLM calls, wrap them too for full trace visibility:

import { eventMetadata } from "@raindrop-ai/ai-sdk";

const summarizeTool = tool({
  description: "Summarize text using AI",
  parameters: z.object({ text: z.string() }),
  execute: async ({ text }) => {
    // Inner wrapper - traces only, no separate event
    const { generateText: innerGenerate } = raindrop.wrap(ai, {
      send: { events: false, traces: true },
    });

    const summary = await innerGenerate({
      model: openai("gpt-4o-mini"),
      prompt: `Summarize: ${text}`,
      experimental_telemetry: {
        isEnabled: true,
        metadata: eventMetadata({ userId: "user_123", eventId }), // Same eventId links traces
      },
    });

    return summary.text;
  },
});

Streaming

Streaming methods (streamText, streamObject) work identically:

import { eventMetadata } from "@raindrop-ai/ai-sdk";

const { streamText } = raindrop.wrap(ai);

const result = await streamText({
  model: openai("gpt-4o"),
  prompt: "Write a haiku about coding",
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({
      userId: "user_123",
      eventName: "haiku-stream",
    }),
  },
});

// Consume the stream
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Raindrop captures streaming-specific metrics:

Time to first chunk (ai.stream.msToFirstChunk)
Total stream duration (ai.stream.msToFinish)
Average output tokens per second (ai.stream.avgOutputTokensPerSecond)

streamObject

streamObject works out of the box. You can await result.object directly without manually consuming the stream:

import { eventMetadata } from "@raindrop-ai/ai-sdk";

const { streamObject } = raindrop.wrap(ai);

const result = await streamObject({
  model: openai("gpt-4o"),
  schema: z.object({ name: z.string(), age: z.number() }),
  prompt: "Generate a person named Alice who is 30",
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({
      userId: "user_123",
      eventName: "person-object-stream",
    }),
  },
});

// This works without consuming partialObjectStream
const person = await result.object;

ToolLoopAgent

Requires AI SDK v6 or later.

ToolLoopAgent is wrapped automatically. Both generate() and stream() trace tool calls with their arguments and results. Pass per-call context via the top-level metadata parameter.

Typescript

raindrop.wrap(ai) changes the ToolLoopAgent method signatures to accept top-level metadata, so typing against ai.ToolLoopAgent can cause TypeScript errors. If you define your own agent type, wrap the AI SDK type with AgentWithMetadata so metadata is still accepted on generate() and stream():

import * as ai from "ai";
import type { ToolSet } from "ai";
import type { AgentWithMetadata } from "@raindrop-ai/ai-sdk";

export type YourToolLoopAgent = AgentWithMetadata<
  ai.ToolLoopAgent<unknown, ToolSet, any>
>;

generate

import * as ai from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import {
  createRaindropAISDK,
  eventMetadata,
} from "@raindrop-ai/ai-sdk";

const raindrop = createRaindropAISDK({
  writeKey: process.env.RAINDROP_WRITE_KEY!,
});

const wrapped = raindrop.wrap(ai);

const weatherTool = ai.tool({
  description: "Get current weather",
  parameters: z.object({ city: z.string() }),
  execute: async ({ city }) => {
    return { temperature: 72, conditions: "sunny" };
  },
});

const agent = new wrapped.ToolLoopAgent({
  model: openai("gpt-4o"),
  tools: { weather: weatherTool },
  maxSteps: 5,
});

const result = await agent.generate({
  prompt: "What's the weather in Tokyo?",
  metadata: eventMetadata({
    userId: "user_123",
    eventName: "agent-weather",
  }),
});

stream

import { eventMetadata } from "@raindrop-ai/ai-sdk";

const result = await agent.stream({
  prompt: "What's the weather in Tokyo?",
  metadata: eventMetadata({
    userId: "user_123",
    eventName: "agent-weather-stream",
  }),
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Signals (Feedback & Instrumentation)

Track user feedback on AI responses using the same eventId:

import { eventMetadata } from "@raindrop-ai/ai-sdk";

const eventId = crypto.randomUUID();

const { generateText } = raindrop.wrap(ai);

const result = await generateText({
  model: openai("gpt-4o"),
  prompt: userMessage,
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({
      userId: "user_123",
      eventId,
      eventName: "chat",
    }),
  },
});

// Later, when user gives feedback
await raindrop.signals.track({
  eventId,
  name: "thumbs_down",
  comment: "Answer was incorrect",
});

Signal Types

Type	Use Case
`"default"`	Generic signals (thumbs up/down)
`"feedback"`	User comments about quality
`"edit"`	User corrected the output
`"standard"`	Programmatic/custom instrumentation
`"agent"`	Self diagnostics issues from `selfDiagnostics`

// Thumbs up
await raindrop.signals.track({
  eventId,
  name: "thumbs_up",
  sentiment: "POSITIVE",
});

// User edit
await raindrop.signals.track({
  eventId,
  name: "user_edit",
  type: "edit",
  after: "The corrected response text",
});

Manual Event Updates

Update events after they’re created:

// Add properties
await raindrop.events.setProperties(eventId, {
  latencyMs: 1234,
  cached: true,
});

// Add attachments
await raindrop.events.addAttachments(eventId, [
  {
    type: "code",
    name: "generated.py",
    value: "print('hello')",
    role: "output",
    language: "python",
  },
]);

// Mark as complete with final output
await raindrop.events.finish(eventId, {
  output: "Final response",
  model: "gpt-4o",
});

Manual Traces

Create trace spans manually alongside (or instead of) auto-instrumented ones. This is useful for:

Extracting DSL commands from agent output as tool-like spans
Adding custom tracing for operations the AI SDK doesn’t auto-instrument
Building full trace trees for custom agent loops (subagents, multi-step workflows)

Spans share the same trace tree as auto-instrumented spans when you pass matching eventId values.

One-shot spans (known timing)

Use createSpan when the operation is already complete and you know the duration:

const eventId = "evt_123";

raindrop.traces.createSpan({
  name: "SET theme=dark",
  eventId,
  operationId: "ai.toolCall",
  input: "SET theme=dark",
  output: "OK",
  durationMs: 12,
});

// Failed span
raindrop.traces.createSpan({
  name: "SET layout=invalid",
  eventId,
  operationId: "ai.toolCall",
  input: "SET layout=invalid",
  error: "Invalid layout value",
  durationMs: 8,
});

Manual lifecycle spans

Use startSpan / endSpan when you want to time an operation in real time:

const span = raindrop.traces.startSpan({
  name: "database_query",
  eventId: "evt_123",
  operationId: "ai.toolCall",
});

try {
  const result = await db.query("SELECT ...");
  raindrop.traces.endSpan(span);
} catch (err) {
  raindrop.traces.endSpan(span, { error: err });
}

Nested spans (subagents)

Pass a span as parent to build a trace tree:

const eventId = "evt_456";

const agentTurn = raindrop.traces.startSpan({
  name: "agent_turn",
  eventId,
});

const subagent = raindrop.traces.startSpan({
  name: "search_subagent",
  eventId,
  parent: agentTurn,
});

raindrop.traces.createSpan({
  name: "grep_search",
  eventId,
  parent: subagent,
  operationId: "ai.toolCall",
  input: { pattern: "execute" },
  output: { matches: 12 },
  durationMs: 120,
});

raindrop.traces.endSpan(subagent);
raindrop.traces.endSpan(agentTurn);

await raindrop.flush();

Mixing with auto-instrumented spans

Use the same eventId for both wrap() calls and manual spans. They appear in the same trace tree:

const eventId = crypto.randomUUID();
const { generateText } = raindrop.wrap(ai, {
  context: { userId: "user_123" },
});

const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "Analyze this data",
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({ eventId }),
  },
});

// Add custom spans to the same event
raindrop.traces.createSpan({
  name: "post_processing",
  eventId,
  input: result.text,
  output: "processed",
  durationMs: 50,
});

await raindrop.flush();

Custom Event Builder

Use buildEvent to customize the event payload from the conversation messages:

import { eventMetadata } from "@raindrop-ai/ai-sdk";

const { generateText } = raindrop.wrap(ai, {
  buildEvent: (messages) => {
    const userMessages = messages.filter(m => m.role === "user");
    const assistantMessages = messages.filter(m => m.role === "assistant");

    return {
      input: userMessages.map(m => m.content).join("\n"),
      output: assistantMessages.pop()?.content,
      eventName: "custom_chat",
      properties: {
        turnCount: userMessages.length,
        hasToolCalls: messages.some(m => m.role === "tool"),
      },
    };
  },
});

await generateText({
  model: openai("gpt-4o"),
  prompt: "Summarize this conversation",
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({ userId: "user_123", eventName: "custom-chat" }),
  },
});

Flush & Shutdown

Always flush before your process exits to ensure all data is sent:

// Serverless: flush at end of request
export async function POST(request: Request) {
  const result = await generateText({ ... });
  await raindrop.flush();
  return Response.json({ text: result.text });
}

// Long-running: shutdown gracefully
process.on("SIGTERM", async () => {
  await raindrop.shutdown();
  process.exit(0);
});

Debugging

Enable debug logging to troubleshoot issues:

const raindrop = createRaindropAISDK({
  writeKey: process.env.RAINDROP_WRITE_KEY!,
  events: { debug: true },
  traces: { debug: true, debugSpans: true },
});

This logs:

Every event sent to Raindrop
Every trace batch shipped
Span parent/child relationships (with debugSpans)

Advanced: Context Propagation APIs

For advanced use cases, access the underlying context propagation utilities:

These APIs are strongest in Node.js (and Cloudflare Workers with nodejs_compat), where they use real AsyncLocalStorage. In edge/browser runtimes they still scope context within the active synchronous call stack, but they do not guarantee propagation across arbitrary async boundaries. In browser/edge runtimes, import them from @raindrop-ai/ai-sdk/browser.

import { currentSpan, withCurrent, getContextManager } from "@raindrop-ai/ai-sdk";

// Get the current span (returns NOOP_SPAN if none)
const span = currentSpan();
console.log(span.eventId, span.traceIdB64);

// Run code within a span context
withCurrent(span, () => {
  // Nested calls inherit this span as parent
  const nested = currentSpan();
  console.log(nested.spanIdB64 === span.spanIdB64); // true
});

// Access the context manager directly
const cm = getContextManager();
const parentIds = cm.getParentSpanIds();

Troubleshooting

Events not appearing in dashboard

Check your write key - Ensure RAINDROP_WRITE_KEY is set correctly
Flush before exit - Call await raindrop.flush() before your process ends
Enable debug logging - Set events: { debug: true } to see what’s being sent

Traces missing or incomplete

Enable trace debugging - Set traces: { debug: true, debugSpans: true }
Check for errors - Look for [raindrop-ai/ai-sdk] prefixed logs

Context not propagating to nested calls

Check your runtime - Full async context propagation requires Node.js (or Cloudflare Workers with nodejs_compat)
Workers import - On Cloudflare Workers with nodejs_compat, import @raindrop-ai/ai-sdk/workers
Browser/edge import - In browser or edge runtimes, import @raindrop-ai/ai-sdk/browser
Edge/browser fallback - In edge/browser runtimes, use an explicit eventId with eventMetadata() when you need correlation across async hops or multiple requests

Ensure nested AI calls use the same eventId and set send: { events: false } to avoid duplicate events:

import { eventMetadata } from "@raindrop-ai/ai-sdk";

const { generateText: innerGenerate } = raindrop.wrap(ai, {
  send: { events: false, traces: true },
});

await innerGenerate({
  model,
  prompt,
  experimental_telemetry: {
    isEnabled: true,
    metadata: eventMetadata({ userId, eventId }),
  },
});

One AI SDK UI turn appears as multiple events

If you use useChat with client-side tools and see one user turn split into multiple events:

Use eventMetadataFromChatRequest() in the route handler so each tool handoff reuses the same logical eventId
Do not generate a fresh eventId on every POST in AI SDK UI routes
Preserve the default AI SDK UI request fields (id, messages, messageId) if you customize the transport body

With the helper in place, client-side tool round-trips reuse one stable eventId and one convoId, which lets the wrapper patch the same logical event instead of creating a new one per hop.

That’s it! You’re ready to explore your events and traces in the Raindrop dashboard. Ping us on Slack or email us if you get stuck!

​Installation

​Quick Start

​Native Telemetry Integration (AI SDK v7+)

​Quick start: registerTelemetry(raindrop())

​Using wrap() with native telemetry

​Direct registration (without wrap())

​When to use native telemetry vs. default wrapping

​Runtime support

​Browsers and edge runtimes

​Node.js (recommended)

​Cloudflare Workers

​Configuration

​Client Options

​Wrap Options

​Projects

​Multiple projects in one process

​Context & Metadata

​Per-Call Context Override (Recommended)

​Feature Flags

​AI SDK UI / useChat with client-side tools

​Identifying Users

​Tools

​Self Diagnostics (Optional)

​Self diagnostics with native telemetry

​Nested LLM Calls in Tools

​Streaming

​streamObject

​ToolLoopAgent

​Typescript

​generate

​stream

​Signals (Feedback & Instrumentation)

​Signal Types

​Manual Event Updates

​Manual Traces

​One-shot spans (known timing)

​Manual lifecycle spans

​Nested spans (subagents)

​Mixing with auto-instrumented spans

​Custom Event Builder

​Flush & Shutdown

​Debugging

​Advanced: Context Propagation APIs

​Troubleshooting

​Events not appearing in dashboard

​Traces missing or incomplete

​Context not propagating to nested calls

​One AI SDK UI turn appears as multiple events

Installation

Quick Start

Native Telemetry Integration (AI SDK v7+)

Quick start: `registerTelemetry(raindrop())`

Using `wrap()` with native telemetry

Direct registration (without `wrap()`)

When to use native telemetry vs. default wrapping

Runtime support

Browsers and edge runtimes

Node.js (recommended)

Cloudflare Workers

Configuration

Client Options

Wrap Options

Projects

Multiple projects in one process

Context & Metadata

Per-Call Context Override (Recommended)

Feature Flags

AI SDK UI / useChat with client-side tools

Identifying Users

Tools

Self Diagnostics (Optional)

Self diagnostics with native telemetry

Nested LLM Calls in Tools

Streaming

streamObject

ToolLoopAgent

Typescript

generate

stream

Signals (Feedback & Instrumentation)

Signal Types

Manual Event Updates

Manual Traces

One-shot spans (known timing)

Manual lifecycle spans

Nested spans (subagents)

Mixing with auto-instrumented spans

Custom Event Builder

Flush & Shutdown

Debugging

Advanced: Context Propagation APIs

Troubleshooting

Events not appearing in dashboard

Traces missing or incomplete

Context not propagating to nested calls

One AI SDK UI turn appears as multiple events