Registry / observability / opentelemetry-instrumentation-openai-agents

opentelemetry-instrumentation-openai-agents

JSON →
library0.62.3pypypi✓ verified 22d ago

This library provides official OpenTelemetry instrumentation for the `openai-agents` SDK, converting the rich trace data emitted by the Agents runtime into the GenAI semantic conventions, enriching spans with request/response payload metadata, and recording duration/token usage metrics. It is currently at version `0.58.0` and maintains an active development pace with frequent updates, often related to compliance with evolving OpenTelemetry Generative AI semantic conventions.

pip install opentelemetry-instrumentation-openai-agents openai-agents opentelemetry-sdk
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-openai-agents
observabilitypythonv0.62.3
Install
9.9s avg
Import
435ms
Disk
95MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.464s · 100.4MB
glibc
py 3.103.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.
fix
Monitor 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.
fix
To 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.
fix
Ensure 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.
Agent activity
24 hits · last 30 days
node
20
Amazon
1
OpenAI (training)
1
Resources
opentelemetry-instrumentation-openai-agents — pip install opentelemetry-instrumentation-openai-agents · libregistry