Metadata-Version: 2.5
Name: raindrop-openai-agents
Version: 0.0.14
Summary: Raindrop integration for OpenAI Agents SDK — automatic tracing of agent runs, LLM generations, tool calls, and handoffs.
Project-URL: Homepage, https://raindrop.ai
Project-URL: Documentation, https://docs.raindrop.ai
Author-email: Raindrop AI <sdk@raindrop.ai>
License-Expression: MIT
License-File: LICENSE
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: raindrop-ai>=0.0.77
Provides-Extra: agents
Requires-Dist: openai-agents>=0.1.0; extra == 'agents'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: requests>=2.28; extra == 'dev'
Description-Content-Type: text/markdown

# raindrop-openai-agents

Raindrop integration for the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) (Python). Implements a `TracingProcessor` that automatically captures agent runs, LLM generations, tool calls, and handoffs and ships them to [Raindrop](https://raindrop.ai).

## Installation

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

## Quick Start

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

```python
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](https://docs.raindrop.ai/platform/projects) by passing its slug as `project_id`:

```python
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]` | `None` | Default user identifier for all events (required to send) |
| `convo_id` | `Optional[str]` | `None` | Group events into a conversation |
| `project_id` | `Optional[str]` | `None` | Route events to a specific [project](https://docs.raindrop.ai/platform/projects) (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 |
| `last_event_id` | `event_id` of the most recent event this wrapper captured, or `None` |
| `resume_interaction(event_id=None)` | Reopen an event (default: `last_event_id`) as a core `Interaction` to update it; `None` when there is nothing to resume |

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

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

## Identify Users

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

## Track Signals

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

## Per-run properties

A run's trace metadata becomes properties on its event:

```python
from agents import RunConfig, Runner

result = await Runner.run(agent, "Hello", run_config=RunConfig(trace_metadata={"plan": "pro"}))
```

## Updating the last event

`last_event_id` is the `event_id` of the most recent agent run. Use it to
attach a signal, or reopen the event with `resume_interaction()` (defaults to
`last_event_id`) and update it through the core SDK's `Interaction`:

```python
interaction = raindrop.resume_interaction()
if interaction is not None:
    interaction.set_properties({"reviewed": True})
    interaction.finish()
```

**Key clashes.** If one of your properties has the same key as one the wrapper
derives itself, your value wins, whichever update carries it (a debug-level log
line names the key). The wrapper's own keys are `ai.*` (for example
`ai.usage.prompt_tokens`), `error`/`error.*` and `openai.*`; avoid them unless
you mean to replace the wrapper's value.

Property-only updates need `raindrop-ai` 0.0.77 or newer; older core
versions drop an update that carries no input or output; the wrapper logs one warning when it resumes an event on such a core.

The OpenAI Agents SDK has one process-wide trace processor, so
`last_event_id` is the most recent run in the process; under concurrent runs
it is whichever run started last.

## Flush & Shutdown

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

## Tool catalog capture (`ai.prompt.tools`)

This wrapper **infers nothing itself**. The Agents SDK trace API it builds on does not show the processor the tool list a model call received: `AgentSpanData.tools` is a list of tool *names* with no schema, `GenerationSpanData` carries no tools, and `ResponseSpanData.response.tools` (the full list) is only filled in when the span ends, after the model span has already started. Inferring a list from any of those would either invent schemas or overstate what the call received, so the wrapper records nothing on its own.

Exact capture comes from the core instead, on the OpenLLMetry OpenAI instrumentor's model spans, which only exist with `disable_auto_instrument=False`; it writes the request's tools to `gen_ai.tool.definitions` (OpenLLMetry 0.62 no longer emits `llm.request.functions.*`), and `raindrop-ai` >= 0.0.72 rebuilds `ai.prompt.tools` from that at export, JSON Schema intact, with OpenAI built-ins (web search, file search, ...) kept as `provider-defined` entries. On `raindrop-ai` 0.0.70 / 0.0.71 the attribute stays absent unless you pass `tools=`; an override replaces the rebuilt list on any version. With the default `disable_auto_instrument=True` the only model spans are the wrapper's own (see [Model spans](#model-spans)); they carry usage, never an inferred tool list, for the reason above (a `tools=` override still reaches the event through `begin`).

Override:

```python
# Default for every run this wrapper traces (goes through begin(..., tools=...))
rd = RaindropOpenAIAgents(api_key="...", user_id="u1", disable_auto_instrument=False,
                          tools=[{"type": "function", "name": "get_weather", "inputSchema": {...}}])

# Per run, through the Agents SDK's own per-run metadata channel
from agents import RunConfig
Runner.run_sync(agent, "weather?", run_config=RunConfig(trace_metadata={"raindrop_tools": [...]}))
```

The per-run value replaces the constructor default; `tools=[]` at either level records an empty catalog. Hosted tools (web search, file search, ...) are recorded as `{"type": "provider-defined", "name": ...}` when you list them that way; the wrapper never invents a schema for them.

Semantics shared with every Raindrop SDK:

- **Attribute absent**: the wrapper could not see the tool list (the wrapper's own model spans never infer one).
- **`[]`**: the model had no tools.
- **Override replaces, never merges.** A `tools=` you pass wins over anything inferred; `tools=[]` records an empty catalog.
- **Content gate.** Tool definitions are prompt content. With `TRACELOOP_TRACE_CONTENT=false` nothing is recorded, overrides included.
- Malformed entries are skipped with a debug log; nothing here raises into your application.

Accepted shapes for `tools=`: canonical `{"type": "function", "name", "description", "inputSchema"}`, OpenAI `{"type": "function", "function": {...}}`, Anthropic `{"name", "description", "input_schema"}`, and `{"type": "provider-defined", "name", ...}`. The core normalises them; the JSON Schema is kept exactly as given.

Needs `raindrop-ai>=0.0.70` (`begin(..., tools=...)`); on an older core the wrapper logs at debug and records nothing.

## User id

Every event needs a real user id: set `user_id=` on the wrapper. Without one (missing, blank, or a placeholder such as `"unknown"` or `"anonymous"`), the event is **not sent** and the wrapper logs one warning; it never raises. Updating an event you resumed with `resume_interaction(event_id=...)` needs no user id, since ingest keeps the one it stored.

## Model spans

With tracing on (the default), the wrapper records each model response in a run as a span on the Raindrop client's tracing. The span carries:

- the model: `gen_ai.provider.name` (canonical name, such as `openai` or `amazon-bedrock`), `gen_ai.request.model` and `gen_ai.response.model`;
- the token usage the provider reports: `gen_ai.usage.input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_write_input_tokens` and `reasoning_tokens`;
- the event it belongs to: `ai.telemetry.metadata.raindrop.eventId` and the `traceloop.association.properties.*` keys.

Token usage also stays on the event as `ai.usage.*` properties. When an OpenTelemetry auto-instrumentation already records the model calls (for example with `auto_instrument=True` on the client), the wrapper adds no span of its own, so a call is never counted twice. Only an instrumentation that traces that call counts: the Agents SDK instrumentor, the OpenAI instrumentor for any call made through the `openai` client (custom endpoints included), the LiteLLM instrumentor for LiteLLM calls, or the provider's own client instrumentation.

The provider comes from what the Agents SDK reports: Responses API calls take the provider of the Agents SDK's default client (`set_default_openai_client`: Azure OpenAI is `azure`; without one, `OPENAI_BASE_URL` or api.openai.com), since their span data names no endpoint; a Responses model built on its own client is labelled by the default client too; Chat Completions calls are named by their endpoint (`api.openai.com`, Azure OpenAI, `api.anthropic.com`, ...), LiteLLM calls by their `provider/model` id. A call to an endpoint the wrapper cannot name gets no `gen_ai.provider.name`, so it goes unpriced rather than priced at another provider's rates.

## Known Limitations

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

## Standard options and flush results

When the wrapper builds its own client, it accepts the core SDK's standard
options by the same names and passes them on:

```python
raindrop = RaindropOpenAIAgents(
    api_key="rk_...",
    user_id="user-123",
    redact_pii=True,        # local PII redaction of event input/output
    flush_timeout=5,        # seconds; deadline for flush() and shutdown()
    debug=True,             # also raises the core SDK's log verbosity
    max_queue_size=5_000,   # any other option `Raindrop(...)` declares
)

result = raindrop.flush()   # the core's FlushResult; safe to ignore
```

- An option the installed `raindrop-ai` does not support is ignored with a
  debug log, never an error. `flush_timeout` and the `FlushResult` return
  value need `raindrop-ai` 0.0.77 or later; on older releases `flush()` and
  `shutdown()` return `None`.
- With `client=` (a `Raindrop` you built), configure these options on that
  client; the wrapper ignores them (debug log).
- `flush()` and `shutdown()` never raise. The result is truthy when
  everything was delivered, and reports `pending`, `dropped` and `timed_out`.

## Full Documentation

[docs.raindrop.ai/integrations/openai-agents](https://docs.raindrop.ai/integrations/openai-agents)

## Application Git metadata

`RaindropOpenAIAgents(...)` and `create_raindrop_openai_agents(...)` accept the keyword-only `app_git` option. It defaults to `True`: explicit Raindrop Git environment or deployment context is applied immediately, and the base SDK may perform one bounded background local-Git lookup from the process working directory. Event capture, flush, and shutdown never wait for that lookup. Pass `False` to disable enrichment, or pass an `AppGitOptions` mapping with `commit_sha`, `commit_dirty`, `branch`, `source_directory`, `detect_branch`, and/or `auto_detect`. Automatic branch discovery remains opt-in through `detect_branch=True` (or `RAINDROP_GIT_DETECT_BRANCH=true`).

For an ordinary in-process application, the process working directory is treated as the application-under-test checkout. A remote, coding, workflow, or observer process must not rely on its own checkout: pass `app_git=False`, provide explicit revision values, or set `source_directory` to the actual application checkout. Canonical per-operation properties remain authoritative. When supplying `client=`, configure `app_git` while constructing that `Raindrop` client; the supplied client is authoritative and the wrapper's `app_git` argument does not reconfigure it.

Release order is deliberate: first publish the base SDK feature, then publish the wrapper feature release with its minimum dependency coordinated to that base release. The existing `raindrop-ai` lower bound remains compatible, but application Git metadata is unavailable on an older core and must not be claimed complete until the base is upgraded. Until coordination assigns a released version, the wrapper checks for an explicit base `app_git` parameter and omits the option when unsupported. Explicit non-default configuration is debug-logged and omitted. Unsupported `app_git` is determined by signature inspection before construction, not by retrying initialization after a `TypeError`; Git configuration adds no initialization attempts and does not change any existing framework-specific initialization fallback.

## Testing

```bash
cd packages/openai-agents-python
pip install -e ".[dev]"
python -m pytest tests/ -v   # unit tests (no external services)
```

End-to-end behavior is verified by the cross-SDK **conformance harness**. This
package ships a thin conformance driver at
[`conformance/driver.py`](conformance/driver.py) that maps the shared scenario
corpus onto the wrapper's public API; known gaps are tracked as ticket-linked
entries in [`conformance/failures.txt`](conformance/failures.txt). The **fault
lane** runs on every PR touching `packages/*-python/**`
(`.github/workflows/conformance-wrappers-python.yml`) against a local capture
server; the **prod lane** verifies delivery by reading back through the public
[Query API](https://docs.raindrop.ai/api-reference/overview). The harness is
pinned by commit SHA (`HARNESS_REF`). See the harness docs:
[HOW-IT-WORKS](https://github.com/invisible-tools/raindrop-sdk-harness/blob/main/docs/HOW-IT-WORKS.md) ·
[AGENTS](https://github.com/invisible-tools/raindrop-sdk-harness/blob/main/AGENTS.md) ·
[README](https://github.com/invisible-tools/raindrop-sdk-harness/blob/main/README.md).

## License

MIT
