@raindrop-ai/openai-agents

Raindrop integration for the OpenAI Agents SDK. Implements a TracingProcessor that captures agent runs, LLM generations, tool calls, and handoffs.

Installation

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

Usage

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, "Hello!");
console.log(result.finalOutput);

await raindrop.flush();

What gets captured

• Agent runs: trace-level events with workflow name
• LLM generations: model, input messages, output, token usage
• Tool calls: function name, input, output
• Handoffs: from/to agent names
• Errors: captured with error status on spans

All spans are linked with parent-child relationships for full trace visibility.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | writeKey | string | - | Raindrop API write key (omit to disable telemetry) | | endpoint | string | https://api.raindrop.ai/v1/ | API endpoint | | userId | string | - | Associate all events with a user | | convoId | string | - | Group events into a conversation | | projectId | string | - | Route events to a specific project (slug); omit for the default Production project | | debug | boolean | false | Enable verbose logging | | maxTextFieldChars | number | 1000000 | Per-field cap for event input/output and serialized span payloads, enforced before/during serialization (truncated values end with ...[truncated by raindrop]; a stricter OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT env var is honored) |

Projects

If your org has multiple projects, route events to a specific one by passing its slug as projectId:

const raindrop = createRaindropOpenAIAgents({
  writeKey: "your-write-key",
  projectId: "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 — the existing behavior. Single-project orgs need nothing new.

Testing

pnpm test

Tests use MSW to intercept HTTP requests — no real OpenAI calls are made.