# @arizeai/openinference-instrumentation-openai-agents

**JavaScript · Instrumentation**

OpenInference instrumentation for OpenAI Agents SDK

- **Version**: 0.3.6
- **Instruments**: `@openai/agents >=0.1.0`

[npm](https://www.npmjs.com/package/@arizeai/openinference-instrumentation-openai-agents) · [README](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/README.md) · [Source](https://github.com/Arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-openai-agents)

## Install

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

## Usage

Register the instrumentation once, at startup, before the library is imported. The [`OpenAIAgentsInstrumentation`](https://openinf.dev/js/openinference-instrumentation-openai-agents.html.md#OpenAIAgentsInstrumentation) reference below lists its options.

```ts
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()`](https://openinf.dev/js/openinference-instrumentation-openai-agents.html.md#OpenAIAgentsInstrumentation.manuallyInstrument).

## `@arizeai/openinference-instrumentation-openai-agents`

### `isPatched`

_function_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/instrumentation.ts#L57)

```typescript
function isPatched(): boolean
```

Check if the agents module is currently instrumented.

### `OpenAIAgentsInstrumentation`

_class_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/instrumentation.ts#L89)

```typescript
class OpenAIAgentsInstrumentation extends InstrumentationBase<typeof AgentsModule>
```

OpenTelemetry-based instrumentation for the [`@openai/agents`](https://www.npmjs.com/package/@openai/agents) SDK.

Registers an [`OpenInferenceTracingProcessor`](https://openinf.dev/js/openinference-instrumentation-openai-agents.html.md#OpenInferenceTracingProcessor) with the SDK’s native tracing system to emit OpenInference-compliant spans without monkey-patching any SDK methods.

**Examples**

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

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

**Examples**

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

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

**Properties**

| Name | Type |
| - | - |
| [`tracer`](https://openinf.dev/js/openinference-instrumentation-openai-agents.html.md#OpenAIAgentsInstrumentation.tracer) | `Tracer` |

#### `new OpenAIAgentsInstrumentation`

_constructor_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/instrumentation.ts#L99)

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

**Parameters**

| 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 `registerInstrumentations` or NodeSDK); it can also be overridden per-call on [`instrument`](https://openinf.dev/js/openinference-instrumentation-openai-agents.html.md#OpenAIAgentsInstrumentation.instrument) and [`manuallyInstrument`](https://openinf.dev/js/openinference-instrumentation-openai-agents.html.md#OpenAIAgentsInstrumentation.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`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/instrumentation.ts#L165)

```typescript
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**

| Name | Type | Description |
| - | - | - |
| `module` | `__module` | The `@openai/agents` module namespace object. |
| `options?` | `OpenAIAgentsInstrumentationOptions` | Controls whether SDK trace processors are replaced or added to. |

#### `instrument`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/instrumentation.ts#L180)

```typescript
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`](https://openinf.dev/js/openinference-instrumentation-openai-agents.html.md#OpenAIAgentsInstrumentation.manuallyInstrument).

#### `uninstrument`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/instrumentation.ts#L201)

```typescript
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`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/instrumentation.ts#L216)

```typescript
setTracerProvider(tracerProvider: TracerProvider): void
```

Sets TraceProvider to this plugin

### `OpenInferenceTracingProcessor`

_class_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/processor.ts#L1129)

```typescript
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`](https://openinf.dev/js/openinference-instrumentation-openai-agents.html.md#OpenAIAgentsInstrumentation.instrument) (preferred) or directly with `setTraceProcessors` / `addTraceProcessor`.

> **See also**
>
> <https://github.com/Arize-ai/openinference/blob/main/spec/attributes/semantic-conventions.md>

#### `new OpenInferenceTracingProcessor`

_constructor_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/processor.ts#L1162)

```typescript
new OpenInferenceTracingProcessor(
  options?: OpenInferenceTracingProcessorOptions,
): OpenInferenceTracingProcessor
```

#### `onTraceStart`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/processor.ts#L1172)

```typescript
onTraceStart(agentTrace: Trace): Promise<void>
```

Called when a trace is started

#### `onTraceEnd`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/processor.ts#L1195)

```typescript
onTraceEnd(agentTrace: Trace): Promise<void>
```

Called when a trace is ended

#### `onSpanStart`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/processor.ts#L1207)

```typescript
onSpanStart(span: Span<SpanData>): Promise<void>
```

Called when a span is started

#### `onSpanEnd`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/processor.ts#L1242)

```typescript
onSpanEnd(span: Span<SpanData>): Promise<void>
```

Called when a span is ended

#### `shutdown`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/processor.ts#L1302)

```typescript
shutdown(_timeout?: number): Promise<void>
```

Called when the trace processor is shutting down

#### `forceFlush`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/processor.ts#L1306)

```typescript
forceFlush(): Promise<void>
```

Called when a trace is being flushed

#### `enable`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/processor.ts#L1310)

```typescript
enable(): void
```

#### `disable`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-instrumentation-openai-agents/src/processor.ts#L1314)

```typescript
disable(): void
```
