# raindrop-openai-agents

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

## Installation

```bash
pip install raindrop-openai-agents openai-agents
```

## Usage

```python
from raindrop_openai_agents import create_raindrop_openai_agents
from agents import Agent, Runner

raindrop = create_raindrop_openai_agents(
    api_key="rk_...",
    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"]()
```

## What gets captured

- **Agent runs**: trace-level events with workflow name
- **LLM generations**: model, input messages, output, token usage
- **Errors**: captured silently (never interferes with agent execution)

## Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api_key` | `str` | required | Raindrop API key |
| `user_id` | `str` | `None` | Associate all events with a user |
| `convo_id` | `str` | `None` | Group events into a conversation |

## Known Limitations

- **Tool calls and handoffs are not captured** — only LLM generation spans are tracked. The TypeScript SDK captures full span trees.
- **Multi-response traces**: In multi-agent workflows, only the last response's data survives.

## Testing

```bash
cd packages/openai-agents-python
pip install -e .
python -m pytest tests/ -v
```
