OpenAI Agents SDK Guide: Tracing, Spans, and Sensitive-Data Controls

InYourLeague Research · 2026-08-27

Answer in brief

OpenAI Agents SDK provides built-in tracing for agent runs, with traces representing end-to-end workflows and spans representing timed operations within those workflows. This reference explains boundaries, background export, flushing, custom processors, and the limits of the supplied evidence for sensitive-data settings, verified on 2026-08-27.

Key facts at a glance

Failure modes and verification

FAQ

Is tracing enabled automatically in OpenAI Agents SDK?

Yes. Tracing is enabled by default, but it can be disabled globally with OPENAI_AGENTS_DISABLE_TRACING=1 or set_tracing_disabled(True), or for one run with RunConfig.tracing_disabled=True. See the official tracing guide.

What is the difference between a trace and a span?

A trace represents one end-to-end logical workflow. A span represents a timed operation inside that workflow and includes its trace relationship, optional parent relationship, and operation-specific data, as described in the official guide.

When should flush_traces() be called?

Call flush_traces() after the trace() context closes when buffered records must be exported immediately at the end of a job. The call blocks until currently buffered traces and spans are exported; it is unnecessary when normal background-export latency is acceptable. See the flush guidance.

What must a custom tracing processor implement?

A TracingProcessor implements trace-start, trace-end, span-start, span-end, shutdown, and forced-flush handling. Its methods should be thread-safe, should not block for long periods, and should handle errors gracefully, according to the API reference.

Does openai-agents-sdk have a selectable model ID?

The official source does not publish a selectable model ID for this product. The tracing documentation describes observability behavior rather than a selectable model identifier; consult the official documentation for the documented product surface.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-27

Extended guide

Direct answer

OpenAI Agents SDK includes built-in tracing and enables it by default. A trace records one end-to-end workflow, while its spans record individual timed operations such as model generations, tool calls, handoffs, and guardrails. The default processor exports buffered records in the background; flush_traces() provides a blocking flush when a unit of work requires immediate delivery. This reference was verified on 2026-08-27.

Core boundaries

By default, the complete Runner.run(), Runner.run_sync(), or Runner.run_streamed() operation is wrapped in trace(). The hierarchy also includes task_span() for each runner invocation, turn_span() for each model turn, and spans for agent runs, generations, function tools, guardrails, handoffs, transcription, speech, and related speech groups. The default trace name is Agent workflow. Setting RunConfig(tracing={"include_task_and_turn_spans": False}) removes automatic task and turn spans while retaining agent, generation, function, guardrail, handoff, and custom spans. See the tracing guide.

Recommended configuration sequence

1. Decide whether the default trace boundary matches the application’s logical workflow. Wrap several runner calls in one explicit trace() when they belong to a single higher-level operation.
2. Keep the normal hierarchy when task and turn details are useful. Set include_task_and_turn_spans to False only when a more compact hierarchy is preferred.
3. Accept background export when modest dashboard delay is acceptable. BatchTraceProcessor exports every few seconds, exports earlier when its in-memory queue reaches its size trigger, and performs a final flush when the process exits.
4. For a worker job requiring immediate delivery, close the trace() context and then call flush_traces(). The call blocks until currently buffered traces and spans are exported; calling it after closure avoids flushing a partially built trace.
5. Add a custom TracingProcessor when records must also go to another destination or replace the default destination. Implement on_trace_start, on_trace_end, on_span_start, on_span_end, shutdown, and force_flush as documented in the API reference.

Sensitive-data controls

The supplied official excerpts establish that tracing can be disabled globally with OPENAI_AGENTS_DISABLE_TRACING=1 or set_tracing_disabled(True), and per run with RunConfig.tracing_disabled=True. They also state that tracing is unavailable to organizations using OpenAI APIs under a Zero Data Retention policy. Although the guide contains a Sensitive data section, the supplied excerpts do not state additional setting names or their precise behavior. Therefore, this reference does not infer undocumented sensitive-data options; consult the current official tracing guide before configuring data capture.

Checklist

• Define the logical trace boundary and meaningful workflow_name.
• Use group_id only when related traces must be linked, such as traces from one conversation.
• Decide whether task and turn spans should remain enabled.
• Place flush_traces() after the trace context when immediate export is required.
• Make custom processor methods thread-safe, avoid long blocking work, and handle errors without disrupting agent execution.
• Review sensitive-data requirements and ZDR compatibility against the official guide.
• Confirm whether tracing should be disabled globally or for an individual run.

Model reference

The official source does not publish a selectable model ID for this product.

Model availability note: The official source does not specify a selectable model ID.