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
Configuration
Projects
Route events to a specific project by passing its slug asprojectId (project_id in Python):
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 inraindrop-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:
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 callflush() 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.