Registry /
observability / openinference-instrumentation-openai-agents
Install & Compatibility
Where this runs
tested against v1.6.1 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 56.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.3s · import 0.000s · 55MB
55MB installed
● package 55MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenAIInstrumentor
✓ from openinference.instrumentation.openai_agents import OpenAIInstrumentor
This quickstart demonstrates how to instrument an OpenAI Assistants API workflow. It sets up an OpenTelemetry TracerProvider, instruments the OpenAI library, creates an assistant, thread, message, and runs the assistant, capturing traces for each step. Remember to set your `OPENAI_API_KEY` environment variable.
import os
import time
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter
from openinference.instrumentation.openai_agents import OpenAIInstrumentor
import openai
# 1. Setup OpenTelemetry (before instrumentation)
resource = Resource.create({"service.name": "openai-agents-quickstart"})
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)
# 2. Instrument OpenAI Agents
OpenAIInstrumentor().instrument()
# 3. Initialize OpenAI Client
# Ensure OPENAI_API_KEY is set in your environment
client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY", ""))
try:
# 4. Interact with OpenAI Assistants API
assistant = client.beta.assistants.create(
name="Math Tutor",
instructions="You are a personal math tutor. Answer questions briefly.",
model="gpt-4o",
)
print(f"Created Assistant: {assistant.id}")
thread = client.beta.threads.create()
print(f"Created Thread: {thread.id}")
message = client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="What is 1 + 1?",
)
print(f"Added Message: {message.id}")
run = client.beta.threads.runs.create(
thread_id=thread.id,
assistant_id=assistant.id,
instructions="Please address the user as Professor."
)
print(f"Started Run: {run.id}")
# 5. Wait for the run to complete (simulated polling)
while run.status in ['queued', 'in_progress', 'cancelling']:
time.sleep(1)
run = client.beta.threads.runs.retrieve(
thread_id=thread.id,
run_id=run.id
)
print(f"Run status: {run.status}")
# 6. Retrieve messages after the run
messages = client.beta.threads.messages.list(
thread_id=thread.id
)
print("\nConversation:")
for m in reversed(messages.data):
print(f"{m.role}: {m.content[0].text.value}")
except openai.APIAssistantError as e:
print(f"OpenAI API Error: {e}")
print("Please ensure you have an OpenAI API key set and have access to the Assistants API.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
finally:
# Clean up resources
try:
if 'thread' in locals() and thread.id:
client.beta.threads.delete(thread.id)
print(f"Deleted Thread: {thread.id}")
if 'assistant' in locals() and assistant.id:
client.beta.assistants.delete(assistant.id)
print(f"Deleted Assistant: {assistant.id}")
except Exception as e:
print(f"Error during cleanup: {e}")
Debug
Known issues
breakingThis instrumentation is designed for `openai` library versions 1.0.0 and above. Using `openai` versions 0.x.x will lead to `AttributeError` or incorrect instrumentation as the API structure changed significantly.fixUpgrade your `openai` library to version `1.0.0` or higher (`pip install 'openai>=1.0.0,<2'`).
affects: <1.0.0 (openai library)
gotchaThe OpenTelemetry `TracerProvider` must be configured and set *before* calling `OpenAIInstrumentor().instrument()`. If the order is reversed, the instrumentation might not pick up the `TracerProvider`, resulting in no traces being emitted.fixAlways ensure your OpenTelemetry SDK setup (e.g., `trace.set_tracer_provider(...)`) is executed prior to calling `OpenAIInstrumentor().instrument()`.
affects: All
gotchaBy default, the instrumentation captures full inputs and outputs, which may include sensitive or personally identifiable information (PII). Be mindful of data privacy requirements.fixTo prevent sensitive data from being exported, configure `OpenAIInstrumentor` with `hide_inputs=True` and/or `hide_outputs=True` when initializing, e.g., `OpenAIInstrumentor(hide_inputs=True, hide_outputs=True).instrument()`.
affects: All
Upgrade
Version history
1.6.1latest on PyPI · released Jun 5, 2026
Audit
Dependencies
openinference-instrumentationrequiredCore OpenInference instrumentation utilities.
openairequiredThe OpenAI Python client library, specifically for the Assistants API (OpenAI Agents). Requires >=1.0.0.
opentelemetry-sdkrequiredThe OpenTelemetry SDK is required for trace context propagation and exporting spans.