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 AX, Jaeger, or your collector of choice.
Installation
npm install @arizeai/openinference-instrumentation-openai-agents @arizeai/openinference-semantic-conventions @openai/agents
Quickstart
import * as agents from "@openai/agents";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { Resource } 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: new Resource({
[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.manuallyInstrument(agents);
// 3. Use the agents SDK as usual.
const agent = new agents.Agent({
name: "Assistant",
instructions: "You are a helpful assistant.",
});
const result = await agents.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() (CommonJS) or manuallyInstrument(agents) (ESM) | Replaces every existing trace processor with the OpenInference one. Use when OpenTelemetry is your sole tracing destination. |
| Additive | instrument({ exclusiveProcessor: false }) (CommonJS) or manuallyInstrument(agents, { exclusiveProcessor: false }) (ESM) | 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. |
When the module is patched automatically (via registerInstrumentations or NodeSDK), choose the mode through the constructor instead: new OpenAIAgentsInstrumentation({ exclusiveProcessor: false }).
To stop tracing, call instrumentation.uninstrument(). In additive mode, the agents SDK does not expose a single-processor removal API, so uninstrument() disables the OpenInference processor in place without clearing other SDK processors.
For ESM-only environments, pass the imported SDK namespace explicitly:
import * as agents from "@openai/agents";
const instrumentation = new OpenAIAgentsInstrumentation({ tracerProvider: provider });
instrumentation.manuallyInstrument(agents, { exclusiveProcessor: false });
Configuration
new OpenAIAgentsInstrumentation({
// Optional: an OTel TracerProvider. Defaults to the global provider.
tracerProvider,
// Optional: processor registration mode (see "How it works" above).
// This is the only way to choose additive mode when the module is patched
// automatically (registerInstrumentations / NodeSDK). Defaults to true.
exclusiveProcessor: true,
// 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,
},
// Optional: maximum number of root trace spans kept in memory while traces
// are in flight. If the limit is exceeded, the oldest root span is ended
// and evicted. Defaults to 1000.
maxRootSpansInFlight: 1000,
});
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
OPENAI_API_KEY=sk-... npx tsx examples/streaming.ts # streamed agent run
OPENAI_API_KEY=sk-... npx tsx examples/guardrail.ts # input guardrail
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
Prompt cache token counts
OpenAI cache reads (cached_tokens) and writes (cache_write_tokens) are recorded as
llm.token_count.prompt_details.cache_read and cache_write. See the
semantic conventions for how these sub-counts relate to the prompt total, and the
cache token example for a Phoenix round trip.