OpenInference Instrumentation for OpenAI Agents SDK (Node.js)

OpenTelemetry-based instrumentation for the OpenAI Agents SDK (@openai/agents). Bridges the SDK's native tracing events to OpenTelemetry spans following the OpenInference semantic conventions, so agent runs can be observed in any OpenTelemetry-compatible backend such as Arize Phoenix, Arize, Jaeger, or your collector of choice.

This is the JavaScript / TypeScript counterpart to the Python openinference-instrumentation-openai-agents package.

Installation

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

Quickstart

import { Agent, run } from "@openai/agents";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

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

// 1. Configure OpenTelemetry.
const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: "my-agent-app",
  }),
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({ url: "http://localhost:6006/v1/traces" }),
    ),
  ],
});
provider.register();

// 2. Register the OpenInference processor with the agents SDK.
const instrumentation = new OpenAIAgentsInstrumentation({ tracerProvider: provider });
instrumentation.instrument();

// 3. Use the agents SDK as usual.
const agent = new Agent({
  name: "Assistant",
  instructions: "You are a helpful assistant.",
});

const result = await run(agent, "What is the capital of France?");
console.log(result.finalOutput);

How it works

Unlike most OpenInference instrumentations, this package does not monkey-patch the SDK. The agents SDK exposes a first-class TracingProcessor interface; this package implements it and registers via the SDK's setTraceProcessors / addTraceProcessor APIs.

| Mode | Call | Behaviour | | --- | --- | --- | | Exclusive (default) | instrument() | Replaces every existing trace processor with the OpenInference one. Use when OpenTelemetry is your sole tracing destination. | | Additive | instrument({ exclusiveProcessor: false }) | Adds the OpenInference processor alongside any existing processors (e.g. the SDK's default OpenAI tracing exporter). Use when you want OpenInference and OpenAI native tracing. |

To stop tracing, call instrumentation.uninstrument().

Configuration

new OpenAIAgentsInstrumentation({
  // Optional: an OTel TracerProvider. Defaults to the global provider.
  tracerProvider,

  // Optional: OpenInference trace configuration for masking/redacting
  // sensitive data on emitted spans.
  // See https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-core
  traceConfig: {
    hideInputs: true,
    hideOutputs: true,
  },
});

Span coverage

Each agents SDK span type is mapped to an OpenInference span kind:

| SDK span | openinference.span.kind | Captured attributes | | --- | --- | --- | | agent | AGENT | graph.node.id, graph.node.parent_id (on handoff destination) | | generation | LLM | llm.model_name, llm.invocation_parameters, llm.input_messages.*, llm.output_messages.*, llm.token_count.{prompt,completion,total}, llm.token_count.prompt_details.cache_read, llm.token_count.completion_details.reasoning | | response | LLM | All of the above plus llm.tools.*, system instructions as input message 0 | | function | TOOL | tool.name, input.value, output.value | | handoff | TOOL | Span name handoff to <to_agent>; the destination agent receives graph.node.parent_id linking back to the source | | mcp_tools | TOOL | output.value (JSON list of tool names) | | guardrail | GUARDRAIL | tool.name, guardrail.triggered | | custom | CHAIN | output.value (JSON-serialised user data) |

Both the chat_completions and responses transports are supported. In chat_completions mode the SDK stores raw response objects in output[]; this instrumentation extracts messages from choices[].message and accumulates token usage across all responses.

Examples

cd js/packages/openinference-instrumentation-openai-agents
pnpm install
pnpm -r build

OPENAI_API_KEY=sk-... npx tsx examples/chat.ts     # single agent + tool call
OPENAI_API_KEY=sk-... npx tsx examples/handoff.ts  # multi-agent handoff

The shared OTel setup lives in examples/instrumentation.ts — modify it to swap in an OTLP exporter or any other span processor.

License

Apache-2.0