Quickstart

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

1from respan import Respan, propagate_attributes
2from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor
3from agents import Agent, Runner
4
5respan = Respan(
6 api_key="your-api-key",
7 instrumentations=[OpenAIAgentsInstrumentor()],
8)
9
10agent = Agent(name="assistant", instructions="You are helpful.")
11
12async def handle_request(user_id: str, message: str):
13 with propagate_attributes(
14 customer_identifier=user_id,
15 thread_identifier="conv_123",
16 ):
17 result = await Runner.run(agent, message)
18 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:

1from respan import (
2 # Core
3 Respan,
4 Instrumentation,
5
6 # Decorators
7 workflow, task, agent, tool,
8
9 # Client
10 RespanClient, get_client,
11
12 # Context managers
13 propagate_attributes,
14 respan_span_attributes,
15)

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