JavaScript APIopenai-agents

Core

Instrumentation

Integrations

JavaScript · Instrumentation

@arizeai/openinference-instrumentation-openai-agents

OpenInference instrumentation for OpenAI Agents SDK

Version
0.3.6
Instruments
@openai/agents >=0.1.0

Install

npm install @arizeai/openinference-instrumentation-openai-agents

Usage

Register the instrumentation once, at startup, before the library is imported. The OpenAIAgentsInstrumentation reference below lists its options.

import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { OpenAIAgentsInstrumentation } from "@arizeai/openinference-instrumentation-openai-agents";

const provider = new NodeTracerProvider({
  // ...a span processor that exports to Phoenix or any OTLP backend.
});
provider.register();

registerInstrumentations({
  instrumentations: [new OpenAIAgentsInstrumentation()],
});

If the library is imported first (as ES modules often are), patch it directly with manuallyInstrument().

@arizeai/openinference-instrumentation-openai-agents

isPatched

functionSource ↗
function isPatched(): boolean

Check if the agents module is currently instrumented.

OpenAIAgentsInstrumentation

classSource ↗
class OpenAIAgentsInstrumentation extends InstrumentationBase<typeof AgentsModule>

OpenTelemetry-based instrumentation for the @openai/agents SDK.

Registers an OpenInferenceTracingProcessor with the SDK’s native tracing system to emit OpenInference-compliant spans without monkey-patching any SDK methods.

Examples

import { NodeSDK } from "@opentelemetry/sdk-node";
import { OpenAIAgentsInstrumentation } from "@arizeai/openinference-instrumentation-openai-agents";

const sdk = new NodeSDK({
  instrumentations: [new OpenAIAgentsInstrumentation()],
});
sdk.start();

Examples

import * as agents from "@openai/agents";
import { OpenAIAgentsInstrumentation } from "@arizeai/openinference-instrumentation-openai-agents";

const instrumentation = new OpenAIAgentsInstrumentation({ tracerProvider: provider });
instrumentation.manuallyInstrument(agents);

Properties

NameType
tracerTracer

new OpenAIAgentsInstrumentation

constructorSource ↗
new OpenAIAgentsInstrumentation(
  options?: {
    exclusiveProcessor?: boolean;
    instrumentationConfig?: InstrumentationConfig;
    traceConfig?: TraceConfigOptions;
    maxRootSpansInFlight?: number;
    tracerProvider?: TracerProvider;
  },
): OpenAIAgentsInstrumentation

Parameters

NameTypeDescription
exclusiveProcessor?boolean

When true (the default), replace all SDK trace processors with the OpenInference processor — the SDK’s default OpenAI tracing exporter is removed. When false, add the OpenInference processor alongside existing processors. This is the only way to choose the mode when the module is patched automatically (e.g. via registerInstrumentations or NodeSDK); it can also be overridden per-call on instrument and manuallyInstrument.

instrumentationConfig?InstrumentationConfig

Standard OTel instrumentation configuration.

traceConfig?TraceConfigOptions

OpenInference trace configuration for masking/redacting sensitive data.

maxRootSpansInFlight?number

Maximum number of root trace spans kept in memory while traces are in flight. Defaults to 1000.

tracerProvider?TracerProvider

Optional custom tracer provider. If not provided, the global provider is used.

manuallyInstrument

methodSource ↗
manuallyInstrument(
  module: __module,
  options?: OpenAIAgentsInstrumentationOptions,
): void

Manually instruments the agents module. Required when the module is not loaded via require() (e.g. ESM environments, bundlers, serverless).

Parameters

NameTypeDescription
module__module

The @openai/agents module namespace object.

options?OpenAIAgentsInstrumentationOptions

Controls whether SDK trace processors are replaced or added to.

instrument

methodSource ↗
instrument(options?: OpenAIAgentsInstrumentationOptions): void

Registers the OpenInference tracing processor with @openai/agents.

This method works synchronously in CommonJS environments. In ESM-only environments, pass the imported module namespace to manuallyInstrument.

uninstrument

methodSource ↗
uninstrument(): void

Removes the registered OpenInference tracing processor from the agents SDK.

Only acts on a module this instance patched: an instance that never patched (e.g. because another instance got there first) is a no-op.

setTracerProvider

methodSource ↗
setTracerProvider(tracerProvider: TracerProvider): void

Sets TraceProvider to this plugin

OpenInferenceTracingProcessor

classSource ↗
class OpenInferenceTracingProcessor implements TracingProcessor

A TracingProcessor that bridges @openai/agents tracing events to OpenTelemetry spans following the OpenInference semantic conventions.

Register it with the agents SDK via OpenAIAgentsInstrumentation.instrument (preferred) or directly with setTraceProcessors / addTraceProcessor.

new OpenInferenceTracingProcessor

constructorSource ↗
new OpenInferenceTracingProcessor(
  options?: OpenInferenceTracingProcessorOptions,
): OpenInferenceTracingProcessor

onTraceStart

methodSource ↗
onTraceStart(agentTrace: Trace): Promise<void>

Called when a trace is started

onTraceEnd

methodSource ↗
onTraceEnd(agentTrace: Trace): Promise<void>

Called when a trace is ended

onSpanStart

methodSource ↗
onSpanStart(span: Span<SpanData>): Promise<void>

Called when a span is started

onSpanEnd

methodSource ↗
onSpanEnd(span: Span<SpanData>): Promise<void>

Called when a span is ended

shutdown

methodSource ↗
shutdown(_timeout?: number): Promise<void>

Called when the trace processor is shutting down

forceFlush

methodSource ↗
forceFlush(): Promise<void>

Called when a trace is being flushed

enable

methodSource ↗
enable(): void

disable

methodSource ↗
disable(): void