Strands Agents (Beta)

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

TypeScript
Python

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

yarn add @raindrop-ai/strands @strands-agents/sdk

pnpm add @raindrop-ai/strands @strands-agents/sdk

pip install raindrop-strands strands-agents

Quick Start

TypeScript
Python

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();

import os
from strands import Agent
from raindrop_strands import RaindropStrands

# 1. Create the Raindrop client
raindrop = RaindropStrands(
    api_key=os.environ["RAINDROP_API_KEY"],
    user_id="user_123",
)

# 2. Create your agent
agent = Agent(
    model="us.amazon.nova-lite-v1:0",
    system_prompt="You are a helpful assistant.",
)

# 3. Register hooks
raindrop.handler.register_hooks(agent)

# 4. Use the agent normally — invocations are traced automatically
result = agent("What is the capital of France?")
print(result)

# 5. Flush before shutdown
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

TypeScript
Python

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
  projectId: "support-prod",   // Optional: route events to a specific project (slug)
  endpoint: "https://...",     // Optional: custom API endpoint
});

raindrop = RaindropStrands(
    api_key="your-write-key",           # Optional: your Raindrop API key (omit to disable telemetry)
    user_id="user-123",        # Optional: associate events with a user
    convo_id="convo-456",      # Optional: conversation/thread ID
    project_id="support-prod", # Optional: route events to a specific project (slug)
    tracing_enabled=True,      # Optional: enable OTEL-based tracing (default: True)
    bypass_otel_for_tools=True,# Optional: bypass OTEL for tool spans (default: True)
    debug=False,               # Optional: enable debug logging (default: False)
)

Projects

Route events to a specific project by passing its slug as projectId (project_id in Python):

TypeScript
Python

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

raindrop = RaindropStrands(
    api_key="your-write-key",
    project_id="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, which is the existing behavior. Single-project orgs need nothing new.

Multiple projects in one process

Available in raindrop-ai>=0.0.56. When one service runs several Strands agents that should report to different projects, create one RaindropStrands wrapper per project. Each wrapper owns its own raindrop.Raindrop client, so the two route independently — there is no shared module-level state:

from raindrop_strands import RaindropStrands

# One long-lived wrapper per project, created at startup and reused.
rd_support = RaindropStrands(api_key="your-write-key", project_id="support-prod")
rd_billing = RaindropStrands(api_key="your-write-key", project_id="billing-prod")

# Register each wrapper's hooks on the corresponding agent.
rd_support.handler.register_hooks(support_agent)   # -> support-prod
rd_billing.handler.register_hooks(billing_agent)   # -> billing-prod

rd_support.flush()
rd_billing.flush()

Each wrapper owns its configuration and delivery pipeline, so agents handled by different wrappers route independently. To share a single client across wrappers (or with the module-level API), construct a raindrop.Raindrop yourself and pass it via client=:

from raindrop import Raindrop

client = Raindrop(api_key="your-write-key", project_id="support-prod")
raindrop = RaindropStrands(client=client)

Identifying Users

TypeScript
Python

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

raindrop.identify(user_id="user_123", traits={"plan": "pro"})

Signals (Feedback)

Track user feedback on AI responses:

TypeScript
Python

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

raindrop.track_signal(
    event_id="evt_...",
    name="thumbs_up",
    signal_type="feedback",
    sentiment="POSITIVE",
)

Flush & Shutdown

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

TypeScript
Python

// Flush pending events
await raindrop.flush();

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

raindrop.flush()       # flush pending data
raindrop.shutdown()    # flush + release resources

Captured Properties

The following properties are automatically included in tracked events:

Property	Description
`ai.usage.prompt_tokens`	Input token count
`ai.usage.completion_tokens`	Output token count
`ai.usage.cached_tokens`	Cached input tokens (Bedrock/Anthropic)
`strands.finish_reason`	Model stop reason (e.g., `end_turn`, `tool_use`)
`error.type`	Exception class name (when an error occurs)
`error.message`	Error message text (truncated to 500 chars)

Token Tracking

The integration automatically captures token usage from model responses:

Property	Description
`ai.usage.prompt_tokens`	Input token count (`inputTokens` from Strands model response)
`ai.usage.completion_tokens`	Output token count (`outputTokens` from Strands model response)
`ai.usage.cached_tokens`	Cached 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:

Python

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!

​Installation

​Quick Start

​What Gets Traced

​Configuration

​Projects

​Multiple projects in one process

​Identifying Users

​Signals (Feedback)

​Flush & Shutdown

​Captured Properties

​Token Tracking

​Finish Reason

​Factory Function

​Known Limitations