Skip to main content

respan-instrumentation-openai-agents

Respan instrumentation plugin for the OpenAI Agents SDK. Captures current 0.20.x agent, task, turn, tool, handoff, guardrail, Responses, Chat Completions, and streaming spans through the OTEL pipeline.

Configuration

1. Install

pip install respan-instrumentation-openai-agents

2. Set Environment Variables

Variable Required Description
RESPAN_API_KEY Yes Your Respan API key. Authenticates both proxy and tracing.
RESPAN_BASE_URL No Defaults to https://api.respan.ai/api.

OPENAI_API_KEY is required when your application calls OpenAI directly. A compatible OpenAI gateway can instead be configured through the Agents SDK's normal custom-client APIs. Hosted Responses tools such as Web Search, File Search, and Computer Use require a Responses-capable OpenAI credential and endpoint; this instrumentation does not convert those tools to Chat Completions.

Quickstart

3. Run Script

import asyncio
import os
from agents import Agent, Runner
from respan import Respan
from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor

respan_api_key = os.environ["RESPAN_API_KEY"]
respan_base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api")

os.environ["OPENAI_API_KEY"] = respan_api_key
os.environ["OPENAI_BASE_URL"] = respan_base_url

respan = Respan(
    api_key=respan_api_key,
    base_url=respan_base_url,
    instrumentations=[OpenAIAgentsInstrumentor()],
)

agent = Agent(name="Assistant", instructions="You are a helpful assistant.")


async def main():
    try:
        result = await Runner.run(agent, "Hello!")
        print(result.final_output)
    finally:
        respan.flush()


asyncio.run(main())

Instrumentation activation is process-wide and reference-counted. Repeated Respan instances share one Agents tracing processor, and the SDK's previous processors are restored after the final deactivation. Auto-emitted spans use canonical JSON attributes, never traceloop.span.kind or the deprecated top-level tool aliases.

4. View Dashboard

After running the script, traces appear on your Respan dashboard.

Sessions

When you set no session id, the trace's group_id (trace(..., group_id=...) or RunConfig(group_id=...)) is sent as the run's Respan session id (respan.sessions.session_identifier), so every turn of one conversation lands in one session with no Respan-specific code.

A session, thread or trace group you set yourself always wins:

from respan import propagate_attributes

with propagate_attributes(session_identifier="my-session"):
    ...  # runs here keep "my-session"

An empty id or one longer than 255 characters is not sent; Respan then detects the session on the server. Unchanged: the trace group (respan.trace.trace_group_identifier) is still sent, and no other span changes.

Further Reading

See the examples/openai-agents-sdk/ directory for runnable examples including tool use, handoffs, multi-agent workflows, guardrails, and streaming.

Metadata

Release files for respan-instrumentation-openai-agents 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for respan-instrumentation-openai-agents 1.2.0
File Size Uploaded Provenance Actions
respan_instrumentation_openai_agents-1.2.0.tar.gz 16.2 kB With provenance Details for respan_instrumentation_openai_agents-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for respan-instrumentation-openai-agents 1.2.0
File Interpreter ABI Platform Actions
respan_instrumentation_openai_agents-1.2.0-py3-none-any.whl Python 3 none any Details for respan_instrumentation_openai_agents-1.2.0-py3-none-any.whl

Total release size: 34.0 kB

Release files / respan_instrumentation_openai_agents-1.2.0.tar.gz

Download URL respan_instrumentation_openai_agents-1.2.0.tar.gz
Size 16.2 kB
Tags Source
SHA-256 checksum
How to use checksums
85fc64219af80408066d567734b78286a1e7ef41529b6105fed3ab48bdf59376
BLAKE2b-256 checksum
How to use checksums
4d289580fad44a155a919275c3fee28d64650fb513dc7b932fc99aaa99790201
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / respan_instrumentation_openai_agents-1.2.0-py3-none-any.whl

Download URL respan_instrumentation_openai_agents-1.2.0-py3-none-any.whl
Size 17.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
19c3e269aef89b5bc0fdb374a78c7e490d340dba152bbf8cefda7e6a0ae2a0be
BLAKE2b-256 checksum
How to use checksums
64c2d532214e84d4f1e372b5684e82aa83f6785ec527d2a6c4357223304d6174
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for respan-instrumentation-openai-agents 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for respan_instrumentation_openai_agents-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page