## Installation

### npm

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

## Quick Start

### TypeScript

```
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

### TypeScript

```
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:

### TypeScript

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

## Track Signals

Attach feedback, labels, or other signals to an existing event:

### TypeScript

```
raindrop.trackSignal("evt_abc123", "thumbs_up", {
  signalType: "feedback",
  sentiment: "POSITIVE",
  comment: "Great answer!",
});
```

## Multi-Agent Workflows

The integration automatically captures handoffs between agents:

### TypeScript

```
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:

### TypeScript

```
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.