OpenAI Agents SDK | Respan Docs

Overview

respan-instrumentation-openai-agents is an instrumentation plugin that captures traces from the OpenAI Agents SDK and sends them to Respan via the unified OTEL pipeline.

It registers a TracingProcessor with the OpenAI Agents SDK that converts native SDK trace/span events into OTEL ReadableSpan objects with proper traceloop.* and gen_ai.* attributes.

$ pip install respan-instrumentation-openai-agents

Version: 1.0.0 | Python: >=3.11, <3.14

Dependencies

Package	Version
`respan-tracing`	>=2.3.0
`respan-sdk`	>=2.5.0
`openai-agents`	>=0.3.1

Quick start

1 from respan import Respan
2 from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor
3 
4 respan = Respan(
5     api_key="your-api-key",
6     instrumentations=[OpenAIAgentsInstrumentor()],
7 )
8 
9 # Now all OpenAI Agents SDK traces are automatically captured
10 from agents import Agent, Runner
11 
12 agent = Agent(name="my-agent", instructions="You are a helpful assistant.")
13 result = await Runner.run(agent, "Hello!")
14 print(result.final_output)

Public API

OpenAIAgentsInstrumentor

The main instrumentor class. Implements the Instrumentation protocol.

1 from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor

Attribute/Method	Type	Description
`name`	`str`	`"openai-agents"` — unique plugin identifier.
`activate()`	`() -> None`	Registers a `TracingProcessor` with the OpenAI Agents SDK via `set_trace_processors()`.
`deactivate()`	`() -> None`	Clears the processor reference.

activate()

When called, activate():

Creates an internal _RespanTracingProcessor instance.
Calls agents.tracing.set_trace_processors([processor]) to replace the default OpenAI tracing backend.
All subsequent traces and spans from the OpenAI Agents SDK are routed through Respan instead of OpenAI’s tracing endpoint.

set_trace_processors() replaces all existing processors. If you need OpenAI’s native tracing alongside Respan, you will need a custom setup.

deactivate()

Clears the internal processor reference. Does not restore the original OpenAI processors.

Captured span types

The plugin captures all span types from the OpenAI Agents SDK:

SDK Span Type	OTEL Span Kind	Log Type	Description
`Trace`	`workflow`	`workflow`	Root trace span (the overall agent run).
`AgentSpanData`	`agent`	`agent`	Agent execution span. Includes agent name, tools, and handoffs.
`ResponseSpanData`	`task`	`response`	LLM response (Responses API call). Includes model, tokens, input/output.
`GenerationSpanData`	`task`	`generation`	LLM generation (Chat Completions API call). Includes model, tokens, input/output.
`FunctionSpanData`	`tool`	`tool`	Tool/function call execution. Includes function name, input, output.
`HandoffSpanData`	`task`	`handoff`	Agent-to-agent handoff. Includes from/to agent names.
`GuardrailSpanData`	`task`	`guardrail`	Guardrail check execution. Includes guardrail name and triggered status.
`CustomSpanData`	`task`	`custom`	Custom user-defined span data.

Span attributes

All spans include these common attributes:

Attribute	Description
`traceloop.span.kind`	Span kind: `"workflow"`, `"agent"`, `"task"`, `"tool"`.
`traceloop.entity.name`	Human-readable span name.
`traceloop.entity.path`	Entity path for parent/child relationship tracking.
`respan.entity.log_type`	Respan log type classification (from `respan-sdk` constants).

LLM spans (ResponseSpanData, GenerationSpanData) additionally include:

Attribute	Description
`llm.request.type`	Always `"chat"` — triggers backend prompt/completion parsing.
`gen_ai.system`	`"openai"` (for ResponseSpanData).
`gen_ai.request.model`	Model name (e.g. `"gpt-4o"`).
`gen_ai.usage.prompt_tokens`	Input token count.
`gen_ai.usage.completion_tokens`	Output token count.
`traceloop.entity.input`	JSON-serialized input messages.
`traceloop.entity.output`	JSON-serialized output.

With propagated attributes

Use propagate_attributes() to attach per-request metadata to all spans:

1 from respan import Respan, propagate_attributes
2 from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor
3 from agents import Agent, Runner
4 
5 respan = Respan(
6     api_key="your-api-key",
7     instrumentations=[OpenAIAgentsInstrumentor()],
8 )
9 
10 agent = Agent(name="assistant", instructions="You are helpful.")
11 
12 async def handle_user_request(user_id: str, message: str):
13     with propagate_attributes(
14         customer_identifier=user_id,
15         thread_identifier="conv_123",
16         metadata={"source": "web"},
17     ):
18         result = await Runner.run(agent, message)
19         return result.final_output

With decorators

Combine plugin instrumentation with decorators for additional context:

1 from respan import Respan, workflow, task
2 from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor
3 from agents import Agent, Runner
4 
5 respan = Respan(
6     api_key="your-api-key",
7     instrumentations=[OpenAIAgentsInstrumentor()],
8 )
9 
10 agent = Agent(name="researcher", instructions="Research the given topic.")
11 
12 @task(name="research")
13 async def research(topic: str):
14     result = await Runner.run(agent, f"Research: {topic}")
15     return result.final_output
16 
17 @workflow(name="research_pipeline")
18 async def pipeline(topics: list[str]):
19     results = []
20     for topic in topics:
21         results.append(await research(topic))
22     return results

Architecture

OpenAI Agents SDK
  │
  ├─ Trace (on_trace_end)  ──→  emit_trace()     ──→  build_readable_span() ──→  inject_span()
  │                                                                                    │
  ├─ AgentSpan (on_span_end) ──→ emit_agent()     ──→  build_readable_span() ──→  inject_span()
  │                                                                                    │
  ├─ ResponseSpan            ──→ emit_response()   ──→  build_readable_span() ──→  inject_span()
  │                                                                                    │
  ├─ FunctionSpan            ──→ emit_function()   ──→  build_readable_span() ──→  inject_span()
  │                                                                                    │
  └─ ...                     ──→ ...               ──→  ...                   ──→  ...
                                                                                       │
                                                                                       ▼
                                                                            OTEL Processor Chain
                                                                                       │
                                                                                       ▼
                                                                            RespanSpanExporter
                                                                                       │
                                                                                       ▼
                                                                              POST /v2/traces

Internal modules

These are implementation details, not part of the public API:

Module	Description
`_instrumentation.py`	`OpenAIAgentsInstrumentor` class and `_RespanTracingProcessor` (the `TracingProcessor` implementation).
`_otel_emitter.py`	Per-type emitter functions (`emit_trace`, `emit_agent`, `emit_response`, etc.) and the `emit_sdk_item()` dispatcher.
`_utils.py`	Serialization helpers: `_serialize()`, `_format_input_messages()`, `_format_output()`, `_parse_ts()`, `_responses_api_item_to_message()`.