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-agentsUsage
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(): booleanCheck 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);new OpenAIAgentsInstrumentation
constructorSource ↗new OpenAIAgentsInstrumentation(
options?: {
exclusiveProcessor?: boolean;
instrumentationConfig?: InstrumentationConfig;
traceConfig?: TraceConfigOptions;
maxRootSpansInFlight?: number;
tracerProvider?: TracerProvider;
},
): OpenAIAgentsInstrumentationParameters
| Name | Type | Description |
|---|---|---|
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 |
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,
): voidManually instruments the agents module. Required when the module is not
loaded via require() (e.g. ESM environments, bundlers, serverless).
Parameters
| Name | Type | Description |
|---|---|---|
module | __module | The |
options? | OpenAIAgentsInstrumentationOptions | Controls whether SDK trace processors are replaced or added to. |
instrument
methodSource ↗instrument(options?: OpenAIAgentsInstrumentationOptions): voidRegisters 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(): voidRemoves 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): voidSets TraceProvider to this plugin
OpenInferenceTracingProcessor
classSource ↗class OpenInferenceTracingProcessor implements TracingProcessorA 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,
): OpenInferenceTracingProcessoronTraceStart
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(): voiddisable
methodSource ↗disable(): void