@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+ andopenai >=7.15.0 <8.
Quick start
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 thesessions.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: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 fromTurn.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.