OpenAI Agents SDK

Bitfab integrates with the OpenAI Agents SDK via a tracing processor that automatically captures agent runs, tool calls, handoffs, and guardrails as traced spans - no manual withSpan or @span decorators needed. To make those runs replayable, a thin run wrapper (wrapRun / wrap_run) records a root span carrying the run input; see Replayable runs with the run wrapper. Canonical signatures: TypeScript reference · Python reference

Supported Languages

Language	Method	Status
TypeScript	`getOpenAiTracingProcessor()` + `getOpenAiAgentHandler()`	✅ Supported
Python	`get_openai_tracing_processor()` + `get_openai_agent_handler()`	✅ Supported
Ruby	-	Not yet supported
Go	-	Not yet supported

Quick Start

import { Bitfab } from "@bitfab/sdk"
import { addTraceProcessor, Agent } from "@openai/agents"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })

// Register the processor once: it captures agent internals (LLM/tool/handoff spans).
addTraceProcessor(bitfab.getOpenAiTracingProcessor())

const agent = new Agent({ name: "my-agent", instructions: "..." })
const handler = bitfab.getOpenAiAgentHandler("my-agent")

// Use wrapRun (a drop-in for run) so the trace gets a replayable root.
const result = await handler.wrapRun(agent, "user input here")

import os
from bitfab import Bitfab
from agents import Agent, add_trace_processor

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"])

# Register the processor once: it captures agent internals (LLM/tool/handoff spans).
add_trace_processor(bitfab.get_openai_tracing_processor())

agent = Agent(name="my-agent", instructions="...")
handler = bitfab.get_openai_agent_handler("my-agent")

# Use wrap_run (a drop-in for Runner.run) so the trace gets a replayable root.
result = await handler.wrap_run(agent, "user input here")

Use addTraceProcessor / add_trace_processor (shown above) to add the Bitfab processor alongside any existing ones. The OpenAI Agents SDK also exposes setTraceProcessors / set_trace_processors, which replaces the entire processor list, including the SDK’s default exporter to the OpenAI platform dashboard. Only use the set form if you want Bitfab to be the sole destination and intend to disable OpenAI’s own tracing.

TypeScript

Installation

npm install @bitfab/sdk @openai/agents

Method Signature

bitfab.getOpenAiTracingProcessor(): BitfabOpenAITracingProcessor

Parameters: None. Returns: A BitfabOpenAITracingProcessor instance that implements the OpenAI Agents SDK TracingProcessor interface.

Usage

import { Bitfab } from "@bitfab/sdk"
import { addTraceProcessor, Agent } from "@openai/agents"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })

// Processor captures agent internals; register once.
addTraceProcessor(bitfab.getOpenAiTracingProcessor())

const agent = new Agent({
  name: "my-agent",
  instructions: "You are a helpful assistant.",
  model: "gpt-4o",
})

// wrapRun is a drop-in for run() that records a replayable root.
const handler = bitfab.getOpenAiAgentHandler("my-agent")
const result = await handler.wrapRun(agent, "What's the weather?")

What Gets Captured

The processor implements the TracingProcessor interface and captures:

Event	What’s Captured
`onTraceStart`	Trace ID, workflow name, group ID
`onTraceEnd`	Trace completion with timing
`onSpanStart`	No payload is sent; the processor waits for the completed span
`onSpanEnd`	The authoritative completed snapshot: IDs, span type, name, output, error (if any), and timing

Span types from the OpenAI Agents SDK (agent, function, generation, guardrail, handoff, etc.) are mapped to Bitfab span data automatically.

Nesting with Core Tracing

If you wrap an agent invocation with withSpan, the OpenAI Agents spans nest as children:

const pipeline = bitfab.getFunction("my-pipeline")

const tracedRun = pipeline.withSpan(
  { name: "RunAgent", type: "agent" },
  async (query: string) => {
    return run(agent, query)
  },
)

await tracedRun("What's the weather?")
// OpenAI Agents spans appear nested under the "RunAgent" span

Error Handling

All processor callbacks are wrapped in try/catch - errors are logged but never thrown. Your agent execution is never affected by tracing failures.

Python

Installation

pip install bitfab-py[openai-tracing]

The openai-tracing extra installs openai-agents as a dependency.

Method Signature

bitfab.get_openai_tracing_processor() -> BitfabOpenAITracingProcessor

Parameters: None. Returns: A BitfabOpenAITracingProcessor instance that implements the OpenAI Agents SDK TracingProcessor interface.

Usage

import os
from bitfab import Bitfab
from agents import Agent, add_trace_processor

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"])

# Processor captures agent internals; register once.
add_trace_processor(bitfab.get_openai_tracing_processor())

agent = Agent(
    name="my-agent",
    instructions="You are a helpful assistant.",
    model="gpt-4o",
)

# wrap_run is a drop-in for Runner.run that records a replayable root.
handler = bitfab.get_openai_agent_handler("my-agent")
result = await handler.wrap_run(agent, "What's the weather?")

What Gets Captured

Same as TypeScript - the processor implements the TracingProcessor interface:

Event	What’s Captured
`on_trace_start`	Trace ID, workflow name, group ID
`on_trace_end`	Trace completion with timing
`on_span_start`	No payload is sent; the processor waits for the completed span
`on_span_end`	The authoritative completed snapshot: IDs, span type, name, output, error (if any), and timing

Nesting with Core Tracing

@bitfab.span("my-pipeline", type="agent")
async def run_agent(query: str):
    return await Runner.run(agent, query)

await run_agent("What's the weather?")
# OpenAI Agents spans appear nested under the "my-pipeline" span

Error Handling

All processor callbacks are wrapped in try/except - errors are logged but never raised. Your agent execution is never affected by tracing failures. Traces flush automatically via atexit hook.

Replayable runs with the run wrapper

The tracing processor captures the agent run for observability, but the processor alone records a root span with no input. The OpenAI Agents agent span is the trace root, and the run input never lands on it (only a response child span carries the model-request input). Replay re-runs the trace’s root span against its recorded input, so a processor-only trace would replay with nothing to feed it. The run wrapper makes a run replayable with no hand-written root. getOpenAiAgentHandler(key).wrapRun (TS) / get_openai_agent_handler(key).wrap_run (Python) is a drop-in for the run call: it opens a keyed root span carrying the run input and final output, and the processor’s auto-captured spans nest underneath. Keep the processor registered for the internals; swap the run call for the wrapper.

import { Bitfab } from "@bitfab/sdk"
import { addTraceProcessor, Agent } from "@openai/agents"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })
addTraceProcessor(bitfab.getOpenAiTracingProcessor()) // captures internals

const agent = new Agent({ name: "my-agent", instructions: "..." })
const handler = bitfab.getOpenAiAgentHandler("my-agent-workflow")

// Swap run(agent, input) -> handler.wrapRun(agent, input)
const result = await handler.wrapRun(agent, "What is 21 + 21?")

// Replay re-runs each recorded input through the same wrapper, by key.
await bitfab.replay("my-agent-workflow", (input: string) =>
  handler.wrapRun(agent, input),
)

import os
from bitfab import Bitfab
from agents import Agent, add_trace_processor

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"])
add_trace_processor(bitfab.get_openai_tracing_processor())  # captures internals

agent = Agent(name="my-agent", instructions="...")
handler = bitfab.get_openai_agent_handler("my-agent-workflow")

# Swap Runner.run(agent, input) -> handler.wrap_run(agent, input)
result = await handler.wrap_run(agent, "What is 21 + 21?")

# Replay re-runs each recorded input through the same wrapper, by key.
await bitfab.replay("my-agent-workflow", lambda input: handler.wrap_run(agent, input))

The wrapper’s root carries the serializable run input, so replay re-runs each historical input through your code by key - no @span/withSpan-decorated function needs to exist. Rebuild runtime wiring inside the callable (agent construction, tools, API keys). Put unsafe calls behind replay-mockable marked spans; use a no-op only for a replay-only callback slot with no recorded call to mock. Alternative: a hand-written root. When there is meaningful work around the run (input prep, orchestration, post-processing), wrap the whole workflow in a withSpan / @span root that takes the workflow input (the same wrap shown in Nesting with Core Tracing). The processor’s spans nest underneath it, and replay re-runs the root against its recorded input. Full details in the Python SDK and TypeScript SDK Replay sections.

Streaming runs

Streamed runs are also traced: the run input lands on the root span and the final output is captured once the stream drains, so first-byte latency is untouched.

// wrapRun is a drop-in for run(agent, input, { stream: true }).
const handler = bitfab.getOpenAiAgentHandler("my-agent-workflow")

const stream = await handler.wrapRun(agent, "Find X", { stream: true })
for await (const event of stream) {
  // handle each streamed event
}
// The root's output is recorded once the stream completes.

# wrap_run_streamed is an async-generator drop-in for Runner.run_streamed:
# iterate it to consume the same stream events while the run is traced.
handler = bitfab.get_openai_agent_handler("my-agent-workflow")

async for event in handler.wrap_run_streamed(agent, "Find X"):
    ...  # handle each streamed event
# The root's output (the run's final_output) is recorded once the stream drains.

In TypeScript, wrapRun returns the streamed run result (drained by the caller) and records the root in the background once it completes. In Python, wrap_run_streamed is itself an async generator that yields each event from Runner.run_streamed(...).stream_events(); the span stays open for the whole iteration so the processor’s spans nest beneath the root.

To replay a recorded run as a regression with bitfab.replay(), use the non-streaming wrapper (wrapRun / wrap_run), which replay re-runs directly. bitfab.replay() does not drive the Python wrap_run_streamed async generator.

Trace metadata

This integration exports its own trace under the same canonical trace id as the traced function, and that export carries metadata of its own. Metadata the caller recorded, through seedTrace / seed_trace or setMetadata / set_metadata, is merged onto that export and takes precedence per key, so a seeded case’s provenance survives and reaches a later replay’s adaptInputs / adapt_inputs hook as ctx.metadata / ctx["metadata"]. Keys the integration set that the caller did not are kept, so ctx.metadata can carry keys the caller never wrote. A key set on both sides to different values keeps the caller’s value and warns once per trace. The merge needs both sides on the same canonical trace id, which is what running the integration nested inside a traced function gives them. A processor-only setup, with no enclosing traced function, resolves its own trace id and has no caller metadata to merge. An export that lands after the traced function returned, as a streamed run’s does, still merges. Requires the TypeScript or Python SDK v0.52.3 or later.

Getting Started

Primitives

Account

SDKs

Framework Integrations

Integrations

Web Portal

Reference

Changelog

OpenAI Agents SDK

Supported Languages

Quick Start

TypeScript

Installation

Method Signature

Usage

What Gets Captured

Nesting with Core Tracing

Error Handling

Python

Installation

Method Signature

Usage

What Gets Captured

Nesting with Core Tracing

Error Handling

Replayable runs with the run wrapper

Streaming runs

Trace metadata

​Supported Languages

​Quick Start

​TypeScript

​Installation

​Method Signature

​Usage

​What Gets Captured

​Nesting with Core Tracing

​Error Handling

​Python

​Installation

​Method Signature

​Usage

​What Gets Captured

​Nesting with Core Tracing

​Error Handling

​Replayable runs with the run wrapper

​Streaming runs

​Trace metadata

Supported Languages

Quick Start

TypeScript

Installation

Method Signature

Usage

What Gets Captured

Nesting with Core Tracing

Error Handling

Python

Installation

Method Signature

Usage

What Gets Captured

Nesting with Core Tracing

Error Handling

Replayable runs with the run wrapper

Streaming runs

Trace metadata