Skip to main content

Documentation Index

Fetch the complete documentation index at: https://raindrop.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

The Strands Agents integration instruments the Strands Agent SDK via its hook system to capture agent invocations, model calls, tool usage, and token metrics. Features:
  • No OpenTelemetry setup required
  • Automatic input/output capture from agent invocations
  • Model call tracking with token usage
  • Tool call span tracking
  • Works with both TypeScript and Python SDKs

​
Installation

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

​
Quick Start

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

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

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

// 3. Register hooks
raindrop.handler.registerHooks(agent);

// 4. Use the agent normally — invocations are traced automatically
const result = await agent("What is the capital of France?");
console.log(result);

// 5. Flush before shutdown
await raindrop.flush();

​
What Gets Traced

The Strands integration automatically captures:
  • Agent invocations — input prompt (last user message), output text, model name
  • Token usage — prompt_tokens, completion_tokens, and cached_tokens (from Bedrock/Anthropic cacheReadInputTokens / cacheCreationInputTokens)
  • Model calls — output and usage extracted from each model call within an invocation
  • Tool call spans — individual tool spans tracked via interaction.track_tool() with name, input, output, duration (ms), and error
  • Finish reason — stop_reason or finish_reason from model responses (e.g., end_turn, tool_use), included in properties as strands.finish_reason
  • Errors — captured and re-raised; telemetry failures never crash your pipeline

​
Configuration

const raindrop = createRaindropStrandsAgents({
  writeKey: "your-write-key",           // Optional: your Raindrop write key (omit to disable telemetry)
  userId: "user-123",          // Optional: associate events with a user
  convoId: "convo-456",        // Optional: conversation/thread ID
  endpoint: "https://...",     // Optional: custom API endpoint
});

​
Identifying Users

await raindrop.users.identify({
  userId: "user_123",
  traits: {
    email: "user@example.com",
    plan: "pro",
  },
});

​
Signals (Feedback)

Track user feedback on AI responses: 
await raindrop.signals.track({
  eventId: "evt_...",
  name: "thumbs_up",
  type: "feedback",
  sentiment: "POSITIVE",
});

​
Flush & Shutdown

Always flush before your process exits to ensure all data is sent: 
// Flush pending events
await raindrop.flush();

// Or shutdown gracefully (flush + release resources)
await raindrop.shutdown();

​
Captured Properties

The following properties are automatically included in tracked events:
PropertyDescription
ai.usage.prompt_tokensInput token count
ai.usage.completion_tokensOutput token count
ai.usage.cached_tokensCached input tokens (Bedrock/Anthropic)
strands.finish_reasonModel stop reason (e.g., end_turn, tool_use)
error.typeException class name (when an error occurs)
error.messageError message text (truncated to 500 chars)

​
Token Tracking

The integration automatically captures token usage from model responses:
PropertyDescription
ai.usage.prompt_tokensInput token count (inputTokens from Strands model response)
ai.usage.completion_tokensOutput token count (outputTokens from Strands model response)
ai.usage.cached_tokensCached input tokens (prefers cacheReadInputTokens, falls back to cacheCreationInputTokens)
Tokens are extracted from both individual model call responses (stop_response.usage) and accumulated metrics (result.metrics.accumulated_usage).

​
Finish Reason

The model’s stop reason is captured automatically and included in event properties as strands.finish_reason. The integration checks stop_reason first (Bedrock convention), then falls back to finish_reason.

​
Factory Function

A create_raindrop_strands() factory is available for convenience: 
from raindrop_strands import create_raindrop_strands

raindrop = create_raindrop_strands(api_key="rk_...")
agent = Agent(model="us.amazon.nova-lite-v1:0")
raindrop.handler.register_hooks(agent)
result = agent("Hello!")
raindrop.flush()

​
Known Limitations

  • Streaming: The integration captures the final result of each model call. Streaming token-by-token output is not individually traced.
  • Multi-agent: Each agent needs its own registerHooks() / register_hooks() call. Nested agent hierarchies are not automatically linked.
  • Python WeakRef: The Python handler uses id(agent) for internal tracking since some agent-like objects don’t support weak references. Context is cleaned up explicitly after each invocation.
That’s it! You’re ready to explore your Strands agent events in the Raindrop dashboard. Ping us on Slack or email us if you get stuck!