Skip to content

Tracing

Tracing Dashboard

This SDK supports OpenAI Traces (traces=v1) compatible tracing.

Defaults

  • Tracing is enabled by default.
  • Each Runner.Run() and Runner.Stream() call is wrapped in a trace named Agent workflow unless you already have an active trace in the context.Context.
  • Spans are emitted for: agent, generation, function/tool, guardrail, and handoff.

Configuration

You can configure tracing per run via RunConfig:

  • TraceWorkflowName: workflow name (default Agent workflow)
  • TraceID: override trace id
  • TraceGroupID: optional grouping id
  • TraceMetadata: optional metadata map
  • TraceEnabled: set to false to disable tracing for that run
  • TraceIncludeSensitiveData: controls inclusion of potentially sensitive request/response/tool I/O
  • TraceAPIKey: override export API key (useful for tracing non-OpenAI model calls while exporting to OpenAI Traces)

Environment variables

  • OPENAI_AGENTS_DISABLE_TRACING=1: disable tracing globally
  • OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=true|false: default sensitive-data behavior
  • OPENAI_API_KEY: used for trace export if no per-trace key is provided
  • OPENAI_ORG_ID, OPENAI_PROJECT_ID: included as export headers when set

Custom exporters/processors

You can replace the global provider used by the SDK:

  • Use tracing.NewBackendSpanExporter() + tracing.NewBatchTracingProcessor(...) + tracing.NewDefaultTraceProvider(...)
  • Call tracing.SetTraceProvider(...) to install it

Tracing

This SDK can emit OpenAI Traces (traces=v1) compatible traces and spans for Runner.Run and Runner.Stream.

Enable tracing export

Tracing is enabled by default unless disabled via environment variable or RunConfig.

To export traces to OpenAI, configure a trace provider with a batch processor and the OpenAI backend exporter:

exporter := tracing.NewBackendSpanExporter()
processor := tracing.NewBatchTracingProcessor(exporter)
provider := tracing.NewDefaultTraceProvider(processor)
tracing.SetTraceProvider(provider)
defer provider.Shutdown(context.Background())

Disabling tracing

  • Global kill switch: set OPENAI_AGENTS_DISABLE_TRACING=1
  • Per-run: set RunConfig.TraceEnabled = ptr(false)

If a trace already exists in the provided context, the runner will not create a new trace.

Workflow / trace / group / metadata

Use RunConfig fields to control trace metadata:

  • TraceWorkflowName
  • TraceID (optional; autogenerated if empty)
  • TraceGroupID
  • TraceMetadata (map[string]any)

Sensitive data

By default, sensitive data is included. You can change defaults or override per-run:

  • Global: OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=0
  • Per-run: RunConfig.TraceIncludeSensitiveData = ptr(false)

When disabled, spans will store "[REDACTED]" for request/response and tool arguments/outputs.