raindrop-openai-agents 0.0.7

Raindrop integration for OpenAI Agents SDK — automatic tracing of agent runs, LLM generations, tool calls, and handoffs.

raindrop-openai-agents

Raindrop integration for the OpenAI Agents SDK (Python). Implements a TracingProcessor that automatically captures agent runs, LLM generations, tool calls, and handoffs and ships them to Raindrop.

Installation

pip install raindrop-openai-agents openai-agents

Quick Start

from raindrop_openai_agents import RaindropOpenAIAgents
from agents import Agent, Runner

raindrop = RaindropOpenAIAgents(
    api_key="your-write-key",
    user_id="user-123",
)
# Processor is auto-registered with the global trace provider

agent = Agent(name="Assistant", model="gpt-4o", instructions="Be helpful")
result = Runner.run_sync(agent, "Hello!")
print(result.final_output)

raindrop.flush()

Factory Function (Legacy)

The create_raindrop_openai_agents() factory is still available and now returns a RaindropOpenAIAgents instance:

from raindrop_openai_agents import create_raindrop_openai_agents

raindrop = create_raindrop_openai_agents(api_key="your-write-key", user_id="user-123")
raindrop.flush()

What Gets Captured

• Agent runs — trace-level events with workflow name
• LLM generations — model, input messages, output text, token usage
• Tool calls — individual tool spans with name, input, output, duration, and error tracking via the Interaction API
• Finish reason — extracted from response status or generation output (ai.finish_reason)
• Extended token categories — cached tokens (ai.usage.cached_tokens) and reasoning/thoughts tokens (ai.usage.thoughts_tokens) for OpenAI o1/o3 models
• Errors — error type and message captured in event properties (never interferes with agent execution)

Projects

Route events to a specific project by passing its slug as project_id:

raindrop = RaindropOpenAIAgents(
    api_key="your-write-key",
    project_id="support-prod",
)

project_id 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. The same option is accepted by the create_raindrop_openai_agents(...) factory. Invalid slugs are ignored with a warning and no header is sent.

API Reference

RaindropOpenAIAgents(api_key, user_id=None, convo_id=None, project_id=None, tracing_enabled=True, bypass_otel_for_tools=True, disable_auto_instrument=True, debug=False)

Parameter	Type	Default	Description
api_key	Optional[str]	None	Raindrop API key (omit to disable telemetry)
user_id	Optional[str]	"unknown"	Default user identifier for all events
convo_id	Optional[str]	None	Group events into a conversation
project_id	Optional[str]	None	Route events to a specific project (slug); omit for the default Production project
tracing_enabled	bool	True	Enable OTEL-based tracing
bypass_otel_for_tools	bool	True	Bypass OTEL instrumentation for tool calls
disable_auto_instrument	bool	True	Library auto-instrumentation is opt-in (see below)
debug	bool	False	Enable verbose debug logging

Library auto-instrumentation is opt-in

As of 0.0.4, disable_auto_instrument defaults to True: the integration no longer lets Traceloop monkey-patch every LLM client library it recognizes in your process (including the OpenAI client the Agents SDK itself drives). The tracing processor captures input/output, token usage, model name, tool calls, and handoffs directly from Agents SDK trace events, so no library patching is needed for full dashboards.

If you specifically want LLM-call-level spans from library instrumentation and have verified compatibility in your environment, opt back in with disable_auto_instrument=False.

Properties

Name	Type	Description
processor	RaindropTracingProcessor	The underlying tracing processor (for manual registration)

Methods

Method	Description
flush()	Flush buffered events to Raindrop
shutdown()	Flush events and release resources
identify(user_id, traits=None)	Identify a user with optional traits
track_signal(event_id, name, signal_type, *, timestamp, properties, attachment_id, comment, after, sentiment)	Attach a signal (feedback, label, etc.) to an existing event

Tool Call Tracking

Tool calls made by agents are automatically captured as individual tool spans. Each span includes:

• Name — the function/tool name
• Input — the arguments passed to the tool
• Output — the tool's return value
• Duration — execution time in milliseconds (computed from SDK span timestamps)
• Error — error message if the tool call failed

Tool spans are tracked via the Raindrop Interaction API (interaction.track_tool()), providing full visibility into agent tool usage alongside LLM generation data.

Extended Token Categories

For OpenAI o1/o3 models that report detailed token breakdowns, the integration captures:

Property	Source	Description
ai.usage.cached_tokens	input_tokens_details.cached_tokens or prompt_tokens_details.cached_tokens	Tokens served from cache
ai.usage.thoughts_tokens	output_tokens_details.reasoning_tokens or completion_tokens_details.reasoning_tokens	Tokens used for internal reasoning

These are reported alongside the standard ai.usage.prompt_tokens and ai.usage.completion_tokens.

Debug Mode

raindrop = RaindropOpenAIAgents(
    api_key="your-write-key",
    debug=True,  # enable verbose logging
)

Identify Users

raindrop.identify("user-42", traits={"plan": "pro", "company": "Acme"})

Track Signals

raindrop.track_signal(
    event_id="evt_abc123",
    name="thumbs_up",
    signal_type="feedback",
    sentiment="POSITIVE",
    comment="Great answer!",
)

Flush & Shutdown

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

Known Limitations

• Multi-response traces — in multi-agent workflows, only the last response's data survives per trace.

Full Documentation

docs.raindrop.ai/integrations/openai-agents

Testing

cd packages/openai-agents-python
pip install -e ".[dev]"
python -m pytest tests/ -v

License

MIT