Registry /
observability / opentelemetry-instrumentation-openai-agents
Install & Compatibility
Where this runs
tested against v0.62.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.464s · 100.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 9.9s · import 0.406s · 99MB
95MB installed
● package 95MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenAIAgentsInstrumentor
✓ from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
This is the main class to initialize the OpenAI Agents instrumentation.
This quickstart demonstrates how to set up the OpenTelemetry Python SDK with an OTLP exporter and then enable instrumentation for OpenAI Agents. After running this code, traces generated by the agent's operations will be sent to the configured OpenTelemetry collector. Make sure an OpenTelemetry collector is running and accessible.
import os
from agents import Agent, Runner, function_tool
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
def configure_otel() -> None:
# Configure an OpenTelemetry TracerProvider
provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Instrument OpenAI Agents
OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)
@function_tool
def get_weather(city: str) -> str:
"""Provides the weather for a given city."""
return f"The forecast for {city} is sunny with pleasant temperatures."
if __name__ == "__main__":
# Ensure OTLP collector is running, e.g., with Docker:
# docker run -d -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector-contrib
# Configure OpenTelemetry
configure_otel()
# Example OpenAI Agent usage
assistant = Agent(
name="Travel Concierge",
instructions="You are a concise travel concierge.",
tools=[get_weather],
)
print("Running agent...")
# Provide dummy API key if required by 'openai-agents', though it might be configured via env vars.
# For real use, ensure OpenAI API key is set via environment variable, e.g., OPENAI_API_KEY
os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'sk-dummy-key-for-example')
result = Runner.run_sync(assistant, "I'm visiting Barcelona this weekend. How should I pack?")
print(f"Agent final output: {result.final_output}")
print("Traces should now be visible in your configured OpenTelemetry backend.")
Debug
Known issues
breakingThe OpenTelemetry Generative AI semantic conventions are under active development and may change. Frequent updates in minor versions (e.g., 0.53.x to 0.58.x) often include migrations and adjustments to these conventions, which can alter span attributes or names.fixMonitor release notes for changes related to GenAI semantic conventions. Consider setting `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` environment variable to opt into the latest experimental conventions, or ensure your telemetry backend is flexible with attribute names.
affects: All versions prior to a stable GenAI semantic convention release (currently experimental)
gotchaBy default, this instrumentation captures message content (prompts, completions, tool arguments) within span attributes, which can include sensitive user data. This behavior might conflict with privacy requirements or increase trace size significantly.fixTo disable content capture, set the environment variable `TRACELOOP_TRACE_CONTENT=false` or `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=no_content` (or equivalent `OTEL_INSTRUMENTATION_OPENAI_AGENTS_CAPTURE_CONTENT` with `ContentCaptureMode.NO_CONTENT`). Other modes like `span_only`, `event_only`, `span_and_event` are available for granular control.
affects: All versions
gotchaThis package (`opentelemetry-instrumentation-openai-agents`) specifically instruments the `openai-agents` SDK. There are other separate instrumentations for the general `openai` client (e.g., `opentelemetry-instrumentation-openai` or `opentelemetry-instrumentation-openai-v2`). Using the wrong instrumentation for your OpenAI integration will result in no telemetry.fixEnsure you are using the correct instrumentation package for the specific OpenAI library or SDK you are interacting with. For `openai-agents` workflows, use this package. For direct `openai` client calls, use `opentelemetry-instrumentation-openai-v2` (the official OpenTelemetry project package) or `opentelemetry-instrumentation-openai` (Traceloop/OpenLLMetry community package) as appropriate.
affects: All versions
Upgrade
Version history
0.62.3latest on PyPI · released Aug 10, 2026
Audit
Dependencies
openai-agentsrequiredThe core library being instrumented.
opentelemetry-apirequiredCore OpenTelemetry API for defining telemetry.
opentelemetry-sdkrequiredOpenTelemetry SDK for processing and exporting telemetry.
opentelemetry-semantic-conventionsrequiredProvides the GenAI semantic conventions used by this instrumentation.