Thanks to visit codestin.com
Credit goes to openai.github.io

Skip to content

Processor interface

TracingProcessor

Bases: ABC

Interface for processing and monitoring traces and spans in the OpenAI Agents system.

This abstract class defines the interface that all tracing processors must implement. Processors receive notifications when traces and spans start and end, allowing them to collect, process, and export tracing data.

Example 
class CustomProcessor(TracingProcessor):
    def __init__(self):
        self.active_traces = {}
        self.active_spans = {}

    def on_trace_start(self, trace):
        self.active_traces[trace.trace_id] = trace

    def on_trace_end(self, trace):
        # Process completed trace
        del self.active_traces[trace.trace_id]

    def on_span_start(self, span):
        self.active_spans[span.span_id] = span

    def on_span_end(self, span):
        # Process completed span
        del self.active_spans[span.span_id]

    def shutdown(self):
        # Clean up resources
        self.active_traces.clear()
        self.active_spans.clear()

    def force_flush(self):
        # Force processing of any queued items
        pass
Notes
  • All methods should be thread-safe
  • Methods should not block for long periods
  • Handle errors gracefully to prevent disrupting agent execution
Source code in src/agents/tracing/processor_interface.py 
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
class TracingProcessor(abc.ABC):
    """Interface for processing and monitoring traces and spans in the OpenAI Agents system.

    This abstract class defines the interface that all tracing processors must implement.
    Processors receive notifications when traces and spans start and end, allowing them
    to collect, process, and export tracing data.

    Example:
        ```python
        class CustomProcessor(TracingProcessor):
            def __init__(self):
                self.active_traces = {}
                self.active_spans = {}

            def on_trace_start(self, trace):
                self.active_traces[trace.trace_id] = trace

            def on_trace_end(self, trace):
                # Process completed trace
                del self.active_traces[trace.trace_id]

            def on_span_start(self, span):
                self.active_spans[span.span_id] = span

            def on_span_end(self, span):
                # Process completed span
                del self.active_spans[span.span_id]

            def shutdown(self):
                # Clean up resources
                self.active_traces.clear()
                self.active_spans.clear()

            def force_flush(self):
                # Force processing of any queued items
                pass
        ```

    Notes:
        - All methods should be thread-safe
        - Methods should not block for long periods
        - Handle errors gracefully to prevent disrupting agent execution
    """

    @abc.abstractmethod
    def on_trace_start(self, trace: "Trace") -> None:
        """Called when a new trace begins execution.

        Args:
            trace: The trace that started. Contains workflow name and metadata.

        Notes:
            - Called synchronously on trace start
            - Should return quickly to avoid blocking execution
            - Any errors should be caught and handled internally
        """
        pass

    @abc.abstractmethod
    def on_trace_end(self, trace: "Trace") -> None:
        """Called when a trace completes execution.

        Args:
            trace: The completed trace containing all spans and results.

        Notes:
            - Called synchronously when trace finishes
            - Good time to export/process the complete trace
            - Should handle cleanup of any trace-specific resources
        """
        pass

    @abc.abstractmethod
    def on_span_start(self, span: "Span[Any]") -> None:
        """Called when a new span begins execution.

        Args:
            span: The span that started. Contains operation details and context.

        Notes:
            - Called synchronously on span start
            - Should return quickly to avoid blocking execution
            - Spans are automatically nested under current trace/span
        """
        pass

    @abc.abstractmethod
    def on_span_end(self, span: "Span[Any]") -> None:
        """Called when a span completes execution.

        Args:
            span: The completed span containing execution results.

        Notes:
            - Called synchronously when span finishes
            - Should not block or raise exceptions
            - Good time to export/process the individual span
        """
        pass

    @abc.abstractmethod
    def shutdown(self) -> None:
        """Called when the application stops to clean up resources.

        Should perform any necessary cleanup like:
        - Flushing queued traces/spans
        - Closing connections
        - Releasing resources
        """
        pass

    @abc.abstractmethod
    def force_flush(self) -> None:
        """Forces immediate processing of any queued traces/spans.

        Notes:
            - Should process all queued items before returning
            - Useful before shutdown or when immediate processing is needed
            - May block while processing completes
        """
        pass

on_trace_start abstractmethod 

on_trace_start(trace: Trace) -> None

Called when a new trace begins execution.

Parameters:

Name Type Description Default
trace Trace

The trace that started. Contains workflow name and metadata.

 required
Notes
  • Called synchronously on trace start
  • Should return quickly to avoid blocking execution
  • Any errors should be caught and handled internally
Source code in src/agents/tracing/processor_interface.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
@abc.abstractmethod
def on_trace_start(self, trace: "Trace") -> None:
    """Called when a new trace begins execution.

    Args:
        trace: The trace that started. Contains workflow name and metadata.

    Notes:
        - Called synchronously on trace start
        - Should return quickly to avoid blocking execution
        - Any errors should be caught and handled internally
    """
    pass

on_trace_end abstractmethod 

on_trace_end(trace: Trace) -> None

Called when a trace completes execution.

Parameters:

Name Type Description Default
trace Trace

The completed trace containing all spans and results.

 required
Notes
  • Called synchronously when trace finishes
  • Good time to export/process the complete trace
  • Should handle cleanup of any trace-specific resources
Source code in src/agents/tracing/processor_interface.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
@abc.abstractmethod
def on_trace_end(self, trace: "Trace") -> None:
    """Called when a trace completes execution.

    Args:
        trace: The completed trace containing all spans and results.

    Notes:
        - Called synchronously when trace finishes
        - Good time to export/process the complete trace
        - Should handle cleanup of any trace-specific resources
    """
    pass

on_span_start abstractmethod 

on_span_start(span: Span[Any]) -> None

Called when a new span begins execution.

Parameters:

Name Type Description Default
span Span[Any]

The span that started. Contains operation details and context.

 required
Notes
  • Called synchronously on span start
  • Should return quickly to avoid blocking execution
  • Spans are automatically nested under current trace/span
Source code in src/agents/tracing/processor_interface.py 
81
82
83
84
85
86
87
88
89
90
91
92
93
@abc.abstractmethod
def on_span_start(self, span: "Span[Any]") -> None:
    """Called when a new span begins execution.

    Args:
        span: The span that started. Contains operation details and context.

    Notes:
        - Called synchronously on span start
        - Should return quickly to avoid blocking execution
        - Spans are automatically nested under current trace/span
    """
    pass

on_span_end abstractmethod 

on_span_end(span: Span[Any]) -> None

Called when a span completes execution.

Parameters:

Name Type Description Default
span Span[Any]

The completed span containing execution results.

 required
Notes
  • Called synchronously when span finishes
  • Should not block or raise exceptions
  • Good time to export/process the individual span
Source code in src/agents/tracing/processor_interface.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
@abc.abstractmethod
def on_span_end(self, span: "Span[Any]") -> None:
    """Called when a span completes execution.

    Args:
        span: The completed span containing execution results.

    Notes:
        - Called synchronously when span finishes
        - Should not block or raise exceptions
        - Good time to export/process the individual span
    """
    pass

shutdown abstractmethod 

shutdown() -> None

Called when the application stops to clean up resources.

Should perform any necessary cleanup like: - Flushing queued traces/spans - Closing connections - Releasing resources

Source code in src/agents/tracing/processor_interface.py 
109
110
111
112
113
114
115
116
117
118
@abc.abstractmethod
def shutdown(self) -> None:
    """Called when the application stops to clean up resources.

    Should perform any necessary cleanup like:
    - Flushing queued traces/spans
    - Closing connections
    - Releasing resources
    """
    pass

force_flush abstractmethod 

force_flush() -> None

Forces immediate processing of any queued traces/spans.

Notes
  • Should process all queued items before returning
  • Useful before shutdown or when immediate processing is needed
  • May block while processing completes
Source code in src/agents/tracing/processor_interface.py 
120
121
122
123
124
125
126
127
128
129
@abc.abstractmethod
def force_flush(self) -> None:
    """Forces immediate processing of any queued traces/spans.

    Notes:
        - Should process all queued items before returning
        - Useful before shutdown or when immediate processing is needed
        - May block while processing completes
    """
    pass

TracingExporter

Bases: ABC

Exports traces and spans. For example, could log them or send them to a backend.

Source code in src/agents/tracing/processor_interface.py 
132
133
134
135
136
137
138
139
140
141
142
class TracingExporter(abc.ABC):
    """Exports traces and spans. For example, could log them or send them to a backend."""

    @abc.abstractmethod
    def export(self, items: list["Trace | Span[Any]"]) -> None:
        """Exports a list of traces and spans.

        Args:
            items: The items to export.
        """
        pass

export abstractmethod 

export(items: list[Trace | Span[Any]]) -> None

Exports a list of traces and spans.

Parameters:

Name Type Description Default
items list[Trace | Span[Any]]

The items to export.

 required
Source code in src/agents/tracing/processor_interface.py 
135
136
137
138
139
140
141
142
@abc.abstractmethod
def export(self, items: list["Trace | Span[Any]"]) -> None:
    """Exports a list of traces and spans.

    Args:
        items: The items to export.
    """
    pass