OpenAI Agents SDK (TypeScript)

Note

Looking for Python? See the Python guide.

This module provides OpenInference instrumentation for the OpenAI Agents SDK for TypeScript (@openai/agents), capturing agent runs, model calls, tool calls, handoffs, and guardrails as OpenInference spans.

Install#

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

Setup#

Use the register function from @arizeai/phoenix-otel to connect to Phoenix, then register the Agents SDK instrumentation.

Create the instrumentation.ts file:

import { register } from "@arizeai/phoenix-otel";import { OpenAIAgentsInstrumentation } from "@arizeai/openinference-instrumentation-openai-agents";import * as agents from "@openai/agents";// Initialize Phoenix tracingexport const provider = register({  projectName: "openai-agents-app",  // If Phoenix is running elsewhere:  // url: "https://your-phoenix.example.com",  // apiKey: process.env.PHOENIX_API_KEY,  // If using self-hosted Phoenix:  // url: "http://localhost:6006",});// Set up OpenAI Agents SDK instrumentationconst instrumentation = new OpenAIAgentsInstrumentation({  tracerProvider: provider,});instrumentation.manuallyInstrument(agents);

Note

The Agents SDK exposes a first-class tracing API, so this instrumentation registers a trace processor with the SDK rather than monkey-patching the module. By default it replaces the SDK’s built-in processors; pass manuallyInstrument(agents, { exclusiveProcessor: false }) to keep OpenAI’s native tracing exporter running alongside Phoenix.

Usage#

import "./instrumentation.js";import { Agent, run } from "@openai/agents";const agent = new Agent({  name: "Assistant",  instructions: "You are a helpful assistant.",});const result = await run(agent, "Explain the theory of relativity in simple terms.");console.log(result.finalOutput);

Note

Spans are exported in batches. In short-lived scripts, call await provider.forceFlush() before the process exits so all spans are delivered to Phoenix.

Observe#

With instrumentation enabled, you will see the following in Phoenix:

AGENT spans for each agent in the run, with graph metadata that lets Phoenix visualize multi-agent handoffs as a graph
LLM spans for model calls, including messages, invocation parameters, and token counts
TOOL spans for function tool calls, handoffs, and MCP tool listings
GUARDRAIL spans for input/output guardrails, including whether the guardrail was triggered

Both the chat completions and responses transports are supported. See the package README for the full span-coverage table and configuration options (including traceConfig for masking sensitive inputs/outputs).

Install#

Setup#

Usage#

Observe#

Resources#