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) 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)

Source distribution for respan-instrumentation-openai-agents 1.2.1
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)

Table of built distributions (wheels) for respan-instrumentation-openai-agents 1.2.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 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