Skip to main content

​
Overview

respan is the recommended way to use Respan. It provides a single Respan() class that sets up tracing, activates instrumentation plugins, and will also initialize the Respan API client when available. 
pip install respan-ai
Version: 3.0.0 | Python: >=3.9, <4.0

​
Quick start

from respan import Respan, propagate_attributes
from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor
from agents import Agent, Runner

respan = Respan(
    api_key="your-api-key",
    instrumentations=[OpenAIAgentsInstrumentor()],
)

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

async def handle_request(user_id: str, message: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_123",
    ):
        result = await Runner.run(agent, message)
        return result.final_output

​
What it does

Respan() is a facade that orchestrates multiple backends: 
Respan(api_key="...", instrumentations=[...])
  │
  ├─ RespanTelemetry   ← OTEL tracing pipeline
  ├─ RespanAPI         ← REST API client (coming soon)
  └─ Plugins           ← Activated instrumentations
You don’t need to interact with RespanTelemetry or RespanAPI directly — Respan handles initialization and configuration for both.

​
Public exports

Everything you need is available from respan: 
from respan import (
    # Core
    Respan,
    Instrumentation,

    # Decorators
    workflow, task, agent, tool,

    # Client
    RespanClient, get_client,

    # Context managers
    propagate_attributes,
    respan_span_attributes,
)

​
When to use respan vs respan-tracing

Use casePackage
Instrument OpenAI Agents, OpenAI SDK, etc.respan
Plugin + decorator comborespan
Decorators only, no pluginsrespan-tracing directly
Building a custom instrumentation pluginrespan-tracing + respan-sdk
Need fine-grained OTEL controlrespan-tracing directly
Most users should use respan. Use respan-tracing directly only when you need manual OTEL configuration.

​
Next steps