Skip to main content
Use @raindrop-ai/openai-managed-agents with the managed OpenAI Agents API, accessed through openai.beta.agents.sessions. It supports hosted and self-hosted session environments, including Astra World Builder. For applications that import Agent, run, or tracing processors from @openai/agents, use the separate OpenAI Agents SDK integration.

Installation

Requires Node.js 22+ and openai >=7.15.0 <8.
Create an OpenAI application key with the required Agents API permissions, and get your Raindrop write key from your project settings.

Quick start

The wrapper preserves native events, abort controls, request options, and withResponse(). Consume parsed events to capture telemetry; raw asResponse() bodies bypass capture.

What is captured

Each turn creates one Raindrop event with its prompt, completed final answer, configured session model, provider, session/turn IDs, and available per-turn token usage. The session ID is the default conversation ID. A root turn span contains child spans for command execution, function calls, MCP calls, web search, and subagent control operations. Function results join their original calls by call ID. Repeated tool receipts and completed turns are deduplicated within the client. The wrapper observes session creation/retrieval, accepted input events, direct event streams, and the sessions.stream helper. Retrieve an existing session through the wrapper before following its events to capture its model. Use one wrapper per native client.

Reconnecting sessions

Use the public typed handler with an unwrapped OpenAI client when a runner reconnects streams. Keep the Raindrop client alive across reconnects and recover stored items before completing the recovered turn snapshot:
Open the stream before recovery so it can buffer live updates. Read and buffer turn statuses first, recover items next, then pass the buffered turns to the handler. A turn completed after the status snapshot stays open until its live terminal event arrives. This keeps its answer and tools ahead of completion. Process callbacks serially during recovery and stream consumption. Call onInputEvents(sessionId, events) after successful tool-result submission. At runner shutdown, stop streams/recovery work, call forgetSession(sessionId), then await raindrop.shutdown(). The simple wrapper closes unfinished captures when the last iterator for a session stops, including early exit and transport failures. This records a capture interruption without cancelling the backend turn. Session model and context remain available across streams; the previous input is cleared. Metadata retains the latest 10,000 idle sessions plus sessions with active turns or streams. Call forgetSession when the session is no longer needed. Stored history listing is not intercepted. Completed-turn deduplication retains the latest 10,000 turns. Supply a stable eventId(turnId) to reuse event identity across process restarts.

Configuration

raindrop.wrap(client, context) overrides context for sessions created or retrieved through that wrapper. Caller-supplied properties and attachments must be redacted by the caller. Use events.patch, events.finish, events.addAttachments, events.setProperties, users.identify, and signals.track to enrich events. Await flush() to ship current buffers. Await shutdown() before process exit to close unfinished captures and ship them.

Known limitations

The managed service does not expose individual inference calls. Capture is per turn. Usage comes only from Turn.usage, is best effort, and may change. Missing counters stay absent; cumulative session usage is never used as turn usage. Revisions after the first terminal receipt are not applied. Automatic capture excludes reasoning text, intermediate commentary, agent-to-agent messages, streaming text deltas, and image contents. Completed final-answer items provide the captured answer. Span timing reflects observed lifecycle events, including recovery. Native turn timestamps are recorded as openai.turn.* attributes. Subagent turns share the conversation and carry their subagent ID; no cross-turn parent hierarchy is inferred. Subagent model identity can differ from the session configuration.
Astra World Builder should send telemetry to its existing authenticated creator callback route. The worker uses a creator session token; the host supplies the Raindrop write key and enforces organization/project scope.