Skip to main content

Installation

Quick Start

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

Projects

Route events to a specific project by passing its slug as projectId (project_id in Python):
This 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. Single-project orgs need nothing new.

Multiple projects in one process (Python)

Available in raindrop-ai>=0.0.56. Each RaindropOpenAIAgents wrapper owns its own raindrop.Raindrop client, so its manual APIs — flush(), identify(), track_signal() — route to that wrapper’s project independently:
Automatic trace capture is process-global and cannot be split by project. The OpenAI Agents SDK exposes a single, process-global trace-processor registry (add_trace_processor, with no removal API), and auto-captured traces carry no project identity. Raindrop therefore registers one processor per process, and automatic capture follows the most recently constructed wrapper: building a second wrapper with a different project_id redirects all automatic agent traces — including those from agents wired under the first wrapper — to the newer project, and emits a runtime warning. Manual APIs (flush/identify/track_signal) still route per wrapper.For automatic capture, use one project per process. If you must stay in one process, construct a single raindrop.Raindrop and share it via client= so there is no ambiguity about where traces land:
Mixed processes — TypeScript (a tracing-enabled raindrop-ai js-sdk client alongside this integration). If the same Node process also constructs a tracing-enabled raindrop-ai js-sdk client, its Traceloop pipeline auto-instruments the underlying LLM libraries process-wide — so calls made through this integration package additionally produce auto-instrumented spans that route to the js-sdk pipeline owner’s project. This is pre-existing behavior, unrelated to per-instance routing. Run mixed setups with a single project, or scope the integration’s calls with the js-sdk client’s asCurrent().

Identify Users

Associate a user identity with optional traits for analytics:

Track Signals

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

Multi-Agent Workflows

The integration automatically captures handoffs between agents:

Tool catalog capture (ai.prompt.tools)

TypeScript. Every response span records the tool catalog the Responses API echoes on its response (function tools with their JSON Schema, hosted tools such as web_search_preview as provider-defined) as ai.prompt.tools. generation spans (Chat Completions) carry no tool definitions, so they record the attribute only when tools is set. Pass tools on createRaindropOpenAIAgents(...) to record a different list (it replaces the inferred one; tools: [] records an empty catalog). Python. raindrop-openai-agents ≥ 0.0.12 infers nothing itself. The Agents SDK trace API the processor builds on never shows it the tool list a model call received: AgentSpanData.tools is a list of names with no schema, GenerationSpanData carries no tools, and ResponseSpanData.response.tools is filled in only when the span ends, after the model span has already started. Inferring from any of those would invent schemas or overstate the call, so the wrapper records nothing on its own. Exact capture comes from the core instead: model spans come from the OpenLLMetry openai instrumentation (disable_auto_instrument=False; with the default True there is no model span at all), which writes the request’s tools to gen_ai.tool.definitions, and raindrop-ai ≥ 0.0.72 rebuilds ai.prompt.tools from that at export, with the JSON Schema intact and OpenAI built-ins (web search, file search, …) kept as provider-defined entries. On 0.0.70 / 0.0.71 the attribute is absent unless you pass tools=; an override replaces the rebuilt list on any version. Pass tools= on RaindropOpenAIAgents(...) / create_raindrop_openai_agents(...) as the default for every run (it goes through begin(..., tools=...)), or per run with Runner.run_sync(agent, input, run_config=RunConfig(trace_metadata={"raindrop_tools": [...]})); the per-run value replaces the default and tools=[] records an empty catalog. Follows TRACELOOP_TRACE_CONTENT; needs raindrop-ai ≥ 0.0.70. See Tool catalog capture for the attribute format, the absent / [] semantics and the override shapes accepted.

Flushing and Shutdown

Always call flush() before your process exits to ensure all telemetry is shipped:

Application Git metadata (Python)

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.

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.