Tracing

The Agents SDK includes built-in tracing, collecting a comprehensive record of events during an agent run: LLM generations, tool calls, handoffs, guardrails, and even custom events that occur. Using the Traces dashboard, you can debug, visualize, and monitor your workflows during development and in production.

Note

Tracing is enabled by default. There are two ways to disable tracing:

You can globally disable tracing by setting the env varOPENAI_AGENTS_DISABLE_TRACING=1
You can disable tracing for a single run by settingagents.run.RunConfig.tracing_disabled toTrue

For organizations operating under a Zero Data Retention (ZDR) policy using OpenAI's APIs, tracing is unavailable.

Traces and spans

Traces represent a single end-to-end operation of a "workflow". They're composed of Spans. Traces have the following properties:
- workflow_name: This is the logical workflow or app. For example "Code generation" or "Customer service".
- trace_id: A unique ID for the trace. Automatically generated if you don't pass one. Must have the formattrace_<32_alphanumeric>.
- group_id: Optional group ID, to link multiple traces from the same conversation. For example, you might use a chat thread ID.
- disabled: If True, the trace will not be recorded.
- metadata: Optional metadata for the trace.
Spans represent operations that have a start and end time. Spans have:
- started_at andended_at timestamps.
- trace_id, to represent the trace they belong to
- parent_id, which points to the parent Span of this Span (if any)
- span_data, which is information about the Span. For example,AgentSpanData contains information about the Agent,GenerationSpanData contains information about the LLM generation, etc.

Default tracing

By default, the SDK traces the following:

The entireRunner.{run, run_sync, run_streamed}() is wrapped in atrace().
Each time an agent runs, it is wrapped inagent_span()
LLM generations are wrapped ingeneration_span()
Function tool calls are each wrapped infunction_span()
Guardrails are wrapped inguardrail_span()
Handoffs are wrapped inhandoff_span()
Audio inputs (speech-to-text) are wrapped in atranscription_span()
Audio outputs (text-to-speech) are wrapped in aspeech_span()
Related audio spans may be parented under aspeech_group_span()

By default, the trace is named "Agent trace". You can set this name if you usetrace, or you can can configure the name and other properties with theRunConfig.

In addition, you can set upcustom trace processors to push traces to other destinations (as a replacement, or secondary destination).

Higher level traces

Sometimes, you might want multiple calls torun() to be part of a single trace. You can do this by wrapping the entire code in atrace().

fromagentsimportAgent,Runner,traceasyncdefmain():agent=Agent(name="Joke generator",instructions="Tell funny jokes.")withtrace("Joke workflow"):# (1)!first_result=awaitRunner.run(agent,"Tell me a joke")second_result=awaitRunner.run(agent,f"Rate this joke:{first_result.final_output}")print(f"Joke:{first_result.final_output}")print(f"Rating:{second_result.final_output}")

Because the two calls toRunner.run are wrapped in awith trace(), the individual runs will be part of the overall trace rather than creating two traces.

Creating traces

You can use thetrace() function to create a trace. Traces need to be started and finished. You have two options to do so:

Recommended: use the trace as a context manager, i.e.with trace(...) as my_trace. This will automatically start and end the trace at the right time.
You can also manually calltrace.start() andtrace.finish().

The current trace is tracked via a Pythoncontextvar. This means that it works with concurrency automatically. If you manually start/end a trace, you'll need to passmark_as_current andreset_current tostart()/finish() to update the current trace.

Creating spans

You can use the various*_span() methods to create a span. In general, you don't need to manually create spans. Acustom_span() function is available for tracking custom span information.

Spans are automatically part of the current trace, and are nested under the nearest current span, which is tracked via a Pythoncontextvar.

Sensitive data

Certain spans may capture potentially sensitive data.

Thegeneration_span() stores the inputs/outputs of the LLM generation, andfunction_span() stores the inputs/outputs of function calls. These may contain sensitive data, so you can disable capturing that data viaRunConfig.trace_include_sensitive_data.

Similarly, Audio spans include base64-encoded PCM data for input and output audio by default. You can disable capturing this audio data by configuringVoicePipelineConfig.trace_include_sensitive_audio_data.

Custom tracing processors

The high level architecture for tracing is:

At initialization, we create a globalTraceProvider, which is responsible for creating traces.
We configure theTraceProvider with aBatchTraceProcessor that sends traces/spans in batches to aBackendSpanExporter, which exports the spans and traces to the OpenAI backend in batches.

To customize this default setup, to send traces to alternative or additional backends or modifying exporter behavior, you have two options:

add_trace_processor() lets you add anadditional trace processor that will receive traces and spans as they are ready. This lets you do your own processing in addition to sending traces to OpenAI's backend.
set_trace_processors() lets youreplace the default processors with your own trace processors. This means traces will not be sent to the OpenAI backend unless you include aTracingProcessor that does so.

Movatterモバイル変換