Skip to main content

​
Installation

npm install @raindrop-ai/openai-agents @openai/agents

​
Quick Start

import { createRaindropOpenAIAgents } from "@raindrop-ai/openai-agents";
import { Agent, run, addTraceProcessor } from "@openai/agents";

const raindrop = createRaindropOpenAIAgents({
  writeKey: "your-write-key",
  userId: "user-123",
});

addTraceProcessor(raindrop.processor);

const agent = new Agent({
  name: "Assistant",
  model: "gpt-4o",
  instructions: "Be helpful",
});

const result = await run(agent, "What is the capital of France?");
console.log(result.finalOutput);

await raindrop.flush();

​
What Gets Traced

The integration captures events from the OpenAI Agents SDK’s built-in tracing system:
  • Agent runs — trace-level events with workflow name and metadata
  • LLM generations — model, input messages, output, token usage (input_tokens/output_tokens)
  • Tool/function calls — function name, input arguments, output, duration, and errors
  • Handoffs — from/to agent names for multi-agent workflows (TypeScript only)
  • Errors — captured with error type and message in event properties
  • 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
In TypeScript, all spans are linked with parent-child relationships for full trace visibility. In Python, tool calls are tracked as individual tool spans via the Interaction API, and LLM generation data is captured per trace.

​
Configuration

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

​
Identify Users

Associate a user identity with optional traits for analytics: 
raindrop.users.identify({ userId: "user-42", traits: { plan: "pro", company: "Acme" } });

​
Track Signals

Attach feedback, labels, or other signals to an existing event: 
raindrop.signals.track({
  eventId: "evt_abc123",
  name: "thumbs_up",
  type: "feedback",
  sentiment: "POSITIVE",
  comment: "Great answer!",
});

​
Multi-Agent Workflows

The integration automatically captures handoffs between agents: 
const triage = new Agent({
  name: "Triage",
  model: "gpt-4o-mini",
  instructions: "Route to the appropriate specialist.",
  handoffs: [specialist],
});

const result = await run(triage, "I need help with billing");
await raindrop.flush();

​
Flushing and Shutdown

Always call flush() before your process exits to ensure all telemetry is shipped: 
await raindrop.flush();     // flush pending data
await raindrop.shutdown();  // flush + release resources

​
Known Limitations (Python)

  • Handoffs are not individually captured in the Python SDK. The TypeScript SDK captures full span trees including handoffs.
  • Multi-response traces: In multi-agent workflows with handoffs, only the last response’s data survives per trace.