@raindrop-ai/mastra

Raindrop integration for Mastra. Automatically captures agent.generate() calls by wrapping the Mastra agent.

Installation

npm install @raindrop-ai/mastra @mastra/core

Usage

import { createRaindropMastra } from "@raindrop-ai/mastra";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

const raindrop = createRaindropMastra({ writeKey: "your-write-key", userId: "user-123" });

const agent = new Agent({
  name: "Assistant",
  model: openai("gpt-4o-mini"),
  instructions: "Be helpful",
});

const wrapped = raindrop.wrap(agent);
const response = await wrapped.generate("Hello!");
console.log(response.text);

await raindrop.shutdown();

What gets captured

• Agent generate: input prompt, output text, model, token usage
• Errors: captured with error status, re-thrown to caller

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | writeKey | string | - | Raindrop API write key (omit to disable telemetry) | | endpoint | string | https://api.raindrop.ai/v1/ | Raindrop API endpoint | | userId | string | - | Associate all events with a user | | convoId | string | - | Group events into a conversation | | projectId | string | - | Route events to a specific project (slug); omit for the default Production project | | debug | boolean | false | Enable verbose logging | | maxTextFieldChars | number | 1000000 | Per-field cap for event input/output and serialized span payloads, enforced before/during serialization (truncated values end with ...[truncated by raindrop]; a stricter OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT env var is honored) | | tools | PromptToolsOverride | undefined | Overrides the tool catalog recorded as ai.prompt.tools on every model span. Use when the integration cannot see the tools the model was given. |

Tool catalog capture

Every generate() span records the agent's registered tool catalog (listTools(), or the legacy tools record) merged with that call's toolsets and clientTools as ai.prompt.tools; zod inputSchemas are converted to JSON Schema through their Standard JSON Schema interface (zod v4). This is the catalog the agent can hand the model, not the exact per-request list the AI SDK call received — Mastra does not expose that list to the wrapper, so an inferred catalog is marked with ai.prompt.tools.source: "mastra.agent.tools" (an explicit tools override carries no source). Each tool is one JSON document in an OTLP string array: {"type":"function","name","description","inputSchema"} for function tools (the JSON Schema is recorded as given — properties, enums, required and per-field descriptions intact) or {"type":"provider-defined","id","name","args"} for provider-owned tools, which get no invented schema. A call without a visible tool list records no attribute; an explicit empty list records []. Pass tools to record a different catalog instead (it replaces the inferred list; tools: [] records an empty catalog).

Projects

If your org has multiple projects, route events to a specific one by passing its slug as projectId:

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

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

Application Git identity

Each client reports the application commit SHA when it can determine one. Local Git discovery runs in the background and never delays or fails application calls. Automatic branch discovery is off by default.

Use appGit to override detection or opt out:

const raindrop = createRaindropMastra({
  writeKey: "your-write-key",
  appGit: {
    commitSha: "0123456789abcdef0123456789abcdef01234567",
    commitDirty: false,
    branch: "main",
    detectBranch: true,
    sourceDirectory: "/path/to/application",
  },
});

// Disable all application Git reporting.
const withoutGit = createRaindropMastra({
  writeKey: "your-write-key",
  appGit: false,
});

commitSha, commitDirty, and branch are explicit overrides. detectBranch opts into automatic branch lookup, sourceDirectory selects the application repository, and autoDetect: false disables automatic sources while retaining explicit values.

Testing

pnpm test