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",
)

Tool catalog capture (`ai.prompt.tools`)

TypeScript. Every strands.model.call span records the agent’s registered tool specs (agent.toolRegistry, the same list the SDK hands the model on each call) as ai.prompt.tools. Pass tools on createRaindropStrands(...) to record a different list instead (it replaces the inferred one; tools: [] records an empty catalog). Python. raindrop-strands ≥ 0.0.13 binds the agent’s registered tool specs (agent.tool_registry.get_all_tool_specs(), the list Strands passes to Model.stream(tool_specs=...) right after the before-model hooks) in on_before_model_call and releases them in on_after_model_call, so the model span opened in between carries ai.prompt.tools with the JSON Schema from inputSchema.json intact. Capture is exact. Pass tools= on RaindropStrands(...) / create_raindrop_strands(...) to record a different list for every model call of every agent registered with that handler (it replaces the registry list; tools=[] records an empty catalog; no per-call override). Follows TRACELOOP_TRACE_CONTENT; needs raindrop-ai ≥ 0.0.70. See Tool catalog capture for the attribute format, the absent / [] semantics and the override shapes accepted.

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

Application Git metadata (Python)

RaindropStrands(...) and create_raindrop_strands(...) accept the keyword-only app_git option. It defaults to True: explicit Raindrop Git environment or deployment context is applied immediately, and the base SDK may perform one bounded background local-Git lookup from the process working directory. Event capture, flush, and shutdown never wait for that lookup. Pass False to disable enrichment, or pass an AppGitOptions mapping with commit_sha, commit_dirty, branch, source_directory, detect_branch, and/or auto_detect. Automatic branch discovery remains opt-in through detect_branch=True (or RAINDROP_GIT_DETECT_BRANCH=true). For an ordinary in-process application, the process working directory is treated as the application-under-test checkout. A remote, coding, workflow, or observer process must not rely on its own checkout: pass app_git=False, provide explicit revision values, or set source_directory to the actual application checkout. Canonical per-operation properties remain authoritative. When supplying client=, configure app_git while constructing that Raindrop client; the supplied client is authoritative and the wrapper’s app_git argument does not reconfigure it. Release order is deliberate: first publish the base SDK feature, then publish the wrapper feature release with its minimum dependency coordinated to that base release. The existing raindrop-ai lower bound remains compatible, but application Git metadata is unavailable on an older core and must not be claimed complete until the base is upgraded. Until coordination assigns a released version, the wrapper checks for an explicit base app_git parameter and omits the option when unsupported. Explicit non-default configuration is debug-logged and omitted. Unsupported app_git is determined by signature inspection before construction, not by retrying initialization after a TypeError; Git configuration adds no initialization attempts and does not change any existing framework-specific initialization fallback.

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!

Getting Started

SDK

Integrations

Platform

Organization

Cookbooks

Workshop

Query API

MCP

Security

Support

Strands Agents (Beta)

Installation

Quick Start

What Gets Traced

Configuration

Projects

Multiple projects in one process

Identifying Users

Signals (Feedback)

Tool catalog capture (`ai.prompt.tools`)

Flush & Shutdown

Captured Properties

Token Tracking

Finish Reason

Factory Function

Application Git metadata (Python)

Known Limitations

​Installation

​Quick Start

​What Gets Traced

​Configuration

​Projects

​Multiple projects in one process

​Identifying Users

​Signals (Feedback)

​Tool catalog capture (ai.prompt.tools)

​Flush & Shutdown

​Captured Properties

​Token Tracking

​Finish Reason

​Factory Function

​Application Git metadata (Python)

​Known Limitations

Installation

Quick Start

What Gets Traced

Configuration

Projects

Multiple projects in one process

Identifying Users

Signals (Feedback)

Tool catalog capture (`ai.prompt.tools`)

Flush & Shutdown

Captured Properties

Token Tracking

Finish Reason

Factory Function

Application Git metadata (Python)

Known Limitations