@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, 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

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