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) on every span of the run (workflow, agent, LLM, tool), 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 on the workflow span.
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.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| respan_instrumentation_openai_agents-1.2.1.tar.gz | 16.5 kB | With provenance | Details for respan_instrumentation_openai_agents-1.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| respan_instrumentation_openai_agents-1.2.1-py3-none-any.whl | Python 3 | none | any | Details for respan_instrumentation_openai_agents-1.2.1-py3-none-any.whl |
Total release size: 34.4 kB
Release files / respan_instrumentation_openai_agents-1.2.1.tar.gz
| Download URL | respan_instrumentation_openai_agents-1.2.1.tar.gz |
|---|---|
| Size | 16.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c690548f2e0cab8505d5d31558519bfe19401fe0d7611f16d23d99685f2966f0
|
|
BLAKE2b-256 checksum How to use checksums |
2e0e88b075c6d52797d83f03844a7c145df23991465ce4dc143669edeabb664f
|
| 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 logRelease files / respan_instrumentation_openai_agents-1.2.1-py3-none-any.whl
| Download URL | respan_instrumentation_openai_agents-1.2.1-py3-none-any.whl |
|---|---|
| Size | 18.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0af8ddf8b7536b95a3a9568f165d4d47d1a44c8da5f536bcf8f900116a1a3d09
|
|
BLAKE2b-256 checksum How to use checksums |
ad201c29010c2063b4e9a3177975f9cec8e67ad12618477ad93c2a69a9391bf8
|
| 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 logSecurity for respan-instrumentation-openai-agents 1.2.1
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.
Attestation for respan_instrumentation_openai_agents-1.2.1.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 logA 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.