@raindrop-ai/strands

Raindrop integration for Strands Agents. Automatically captures agent invocations, model calls, tool usage, and token metrics via the Strands hook system.

Installation

npm install @raindrop-ai/strands @strands-agents/sdk

@strands-agents/sdk is a required peer dependency.

Usage

import { Agent } from "@strands-agents/sdk";
import { createRaindropStrandsAgents } from "@raindrop-ai/strands";

const raindrop = createRaindropStrandsAgents({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  userId: "user_123",
  convoId: "session_456",
});

const agent = new Agent({
  model: "us.amazon.nova-lite-v1:0",
  systemPrompt: "You are a helpful assistant.",
});

raindrop.handler.registerHooks(agent);

const result = await agent("What is the capital of France?");
console.log(result);

await raindrop.shutdown();

Omitting writeKey disables telemetry shipping (a warning is logged) but does not crash your application.

API

createRaindropStrandsAgents(options)

Options: writeKey, endpoint, userId, convoId, projectId, debug, appGit, and maxTextFieldChars (default 1000000) — a per-field cap for event input/output and serialized span payloads, enforced before/during serialization so multi-MB payloads cost the cap, not the payload, on the calling thread. Truncated values end with ...[truncated by raindrop]; a stricter OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT env var is honored. Tool-result span attributes (ai.toolCall.result) keep their pre-existing fixed 4096-char cap and are not governed by this option.

Returns a client with:

• handler — RaindropCallbackHandler instance to register on agents
• events.patch(), events.finish(), events.addAttachments(), events.setProperties() — manual event lifecycle
• users.identify() — associate user traits
• signals.track() — track feedback signals
• flush() — flush pending telemetry
• shutdown() — flush and release resources

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.

const raindrop = createRaindropStrandsAgents({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  appGit: {
    commitSha: "0123456789abcdef0123456789abcdef01234567",
    commitDirty: false,
    branch: "main",
    detectBranch: true,
    sourceDirectory: "/path/to/application",
  },
});

const withoutGit = createRaindropStrandsAgents({
  writeKey: process.env.RAINDROP_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.

Projects

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

const raindrop = createRaindropStrandsAgents({
  writeKey: process.env.RAINDROP_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.

License

MIT