OpenAI Agents SDK
Auto-instrument the OpenAI Agents SDK with the OTel contrib instrumentor and emit GenAI spans in the new semantic conventions.
Before you start
These examples export to a local OpenTelemetry Collector over OTLP/gRPC. Deploy the collector first — see Code examples → Deploy an OpenTelemetry Collector.
Install
pip install openai-agents opentelemetry-instrumentation-openai-agents-v2 opentelemetry-instrumentation-openai-v2 opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc
Environment variables
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://<COLLECTOR_HOST>:4317"
export OTEL_EXPORTER_OTLP_INSECURE="true"
export OTEL_RESOURCE_ATTRIBUTES="cx.application.name=my-genai-app,cx.subsystem.name=my-subsystem"
export OTEL_SEMCONV_STABILITY_OPT_IN="gen_ai_latest_experimental"
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="true"
Script
import asyncio
from agents import Agent, Runner, function_tool
# --- OTel imports ---
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
# --- OTel setup: configure tracer provider and OTLP exporter ---
def configure_otel() -> TracerProvider:
resource = Resource.create()
provider = TracerProvider(resource=resource)
exporter = OTLPSpanExporter() # reads OTEL_EXPORTER_OTLP_ENDPOINT from env
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)
return provider
# --- Your app logic (replace with your own) ---
@function_tool
def get_weather(city: str) -> str:
"""Get the current weather for a city."""
return f"The weather in {city} is 22C and sunny."
async def main():
# OTel: initialize tracing and auto-instrument the OpenAI Agents SDK
provider = configure_otel()
OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)
OpenAIInstrumentor().instrument(tracer_provider=provider)
# Your app logic
agent = Agent(
name="Travel Assistant",
instructions="You are a concise travel assistant. Answer in one sentence.",
tools=[get_weather],
)
result = await Runner.run(agent, input="What's the weather in Paris?")
print(f"Agent response: {result.final_output}")
# OTel: flush and shut down the tracer provider
provider.force_flush()
provider.shutdown()
if __name__ == "__main__":
asyncio.run(main())
Expected span attributes
gen_ai.operation.name="chat"gen_ai.provider.name="openai"gen_ai.request.model,gen_ai.response.modelgen_ai.usage.input_tokens,gen_ai.usage.output_tokensgen_ai.input.messages,gen_ai.output.messages(as log events with content capture)- Agent spans:
gen_ai.agent.name,gen_ai.tool.name
Tip
If pip install fails for pre-release packages, try pip install --pre opentelemetry-instrumentation-openai-agents-v2.
Next steps
Look up which open-source library to use for your provider in Compatibility matrix.
Theme
Light