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 99100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129

classTracingProcessor(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.abstractmethoddefon_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.abstractmethoddefon_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.abstractmethoddefon_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.abstractmethoddefon_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.abstractmethoddefshutdown(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.abstractmethoddefforce_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

103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165

classTraceProvider(ABC):"""Interface for creating traces and spans."""@abstractmethoddefregister_processor(self,processor:TracingProcessor)->None:"""Add a processor that will receive all traces and spans."""@abstractmethoddefset_processors(self,processors:list[TracingProcessor])->None:"""Replace the list of processors with ``processors``."""@abstractmethoddefget_current_trace(self)->Trace|None:"""Return the currently active trace, if any."""@abstractmethoddefget_current_span(self)->Span[Any]|None:"""Return the currently active span, if any."""@abstractmethoddefset_disabled(self,disabled:bool)->None:"""Enable or disable tracing globally."""@abstractmethoddeftime_iso(self)->str:"""Return the current time in ISO 8601 format."""@abstractmethoddefgen_trace_id(self)->str:"""Generate a new trace identifier."""@abstractmethoddefgen_span_id(self)->str:"""Generate a new span identifier."""@abstractmethoddefgen_group_id(self)->str:"""Generate a new group identifier."""@abstractmethoddefcreate_trace(self,name:str,trace_id:str|None=None,group_id:str|None=None,metadata:dict[str,Any]|None=None,disabled:bool=False,)->Trace:"""Create a new trace."""@abstractmethoddefcreate_span(self,span_data:TSpanData,span_id:str|None=None,parent:Trace|Span[Any]|None=None,disabled:bool=False,)->Span[TSpanData]:"""Create a new span."""@abstractmethoddefshutdown(self)->None:"""Clean up any resources used by the provider."""

2829303132333435363738394041424344454647484950515253545556575859

classAgentSpanData(SpanData):"""    Represents an Agent Span in the trace.    Includes name, handoffs, tools, and output type.    """__slots__=("name","handoffs","tools","output_type")def__init__(self,name:str,handoffs:list[str]|None=None,tools:list[str]|None=None,output_type:str|None=None,):self.name=nameself.handoffs:list[str]|None=handoffsself.tools:list[str]|None=toolsself.output_type:str|None=output_type@propertydeftype(self)->str:return"agent"defexport(self)->dict[str,Any]:return{"type":self.type,"name":self.name,"handoffs":self.handoffs,"tools":self.tools,"output_type":self.output_type,}

192193194195196197198199200201202203204205206207208209210211212213

classCustomSpanData(SpanData):"""    Represents a Custom Span in the trace.    Includes name and data property bag.    """__slots__=("name","data")def__init__(self,name:str,data:dict[str,Any]):self.name=nameself.data=data@propertydeftype(self)->str:return"custom"defexport(self)->dict[str,Any]:return{"type":self.type,"name":self.name,"data":self.data,}

6263646566676869707172737475767778798081828384858687888990919293

classFunctionSpanData(SpanData):"""    Represents a Function Span in the trace.    Includes input, output and MCP data (if applicable).    """__slots__=("name","input","output","mcp_data")def__init__(self,name:str,input:str|None,output:Any|None,mcp_data:dict[str,Any]|None=None,):self.name=nameself.input=inputself.output=outputself.mcp_data=mcp_data@propertydeftype(self)->str:return"function"defexport(self)->dict[str,Any]:return{"type":self.type,"name":self.name,"input":self.input,"output":str(self.output)ifself.outputelseNone,"mcp_data":self.mcp_data,}

 96 97 98 99100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136

classGenerationSpanData(SpanData):"""    Represents a Generation Span in the trace.    Includes input, output, model, model configuration, and usage.    """__slots__=("input","output","model","model_config","usage",)def__init__(self,input:Sequence[Mapping[str,Any]]|None=None,output:Sequence[Mapping[str,Any]]|None=None,model:str|None=None,model_config:Mapping[str,Any]|None=None,usage:dict[str,Any]|None=None,):self.input=inputself.output=outputself.model=modelself.model_config=model_configself.usage=usage@propertydeftype(self)->str:return"generation"defexport(self)->dict[str,Any]:return{"type":self.type,"input":self.input,"output":self.output,"model":self.model,"model_config":self.model_config,"usage":self.usage,}

216217218219220221222223224225226227228229230231232233234235236237

classGuardrailSpanData(SpanData):"""    Represents a Guardrail Span in the trace.    Includes name and triggered status.    """__slots__=("name","triggered")def__init__(self,name:str,triggered:bool=False):self.name=nameself.triggered=triggered@propertydeftype(self)->str:return"guardrail"defexport(self)->dict[str,Any]:return{"type":self.type,"name":self.name,"triggered":self.triggered,}

168169170171172173174175176177178179180181182183184185186187188189

classHandoffSpanData(SpanData):"""    Represents a Handoff Span in the trace.    Includes source and destination agents.    """__slots__=("from_agent","to_agent")def__init__(self,from_agent:str|None,to_agent:str|None):self.from_agent=from_agentself.to_agent=to_agent@propertydeftype(self)->str:return"handoff"defexport(self)->dict[str,Any]:return{"type":self.type,"from_agent":self.from_agent,"to_agent":self.to_agent,}

350351352353354355356357358359360361362363364365366367368369370371372373374

classMCPListToolsSpanData(SpanData):"""    Represents an MCP List Tools Span in the trace.    Includes server and result.    """__slots__=("server","result",)def__init__(self,server:str|None=None,result:list[str]|None=None):self.server=serverself.result=result@propertydeftype(self)->str:return"mcp_tools"defexport(self)->dict[str,Any]:return{"type":self.type,"server":self.server,"result":self.result,}

139140141142143144145146147148149150151152153154155156157158159160161162163164165

classResponseSpanData(SpanData):"""    Represents a Response Span in the trace.    Includes response and input.    """__slots__=("response","input")def__init__(self,response:Response|None=None,input:str|list[ResponseInputItemParam]|None=None,)->None:self.response=response# This is not used by the OpenAI trace processors, but is useful for other tracing# processor implementationsself.input=input@propertydeftype(self)->str:return"response"defexport(self)->dict[str,Any]:return{"type":self.type,"response_id":self.response.idifself.responseelseNone,}

111213141516171819202122232425

classSpanData(abc.ABC):"""    Represents span data in the trace.    """@abc.abstractmethoddefexport(self)->dict[str,Any]:"""Export the span data as a dictionary."""pass@property@abc.abstractmethoddeftype(self)->str:"""Return the type of the span."""pass

326327328329330331332333334335336337338339340341342343344345346347

classSpeechGroupSpanData(SpanData):"""    Represents a Speech Group Span in the trace.    """__slots__="input"def__init__(self,input:str|None=None,):self.input=input@propertydeftype(self)->str:return"speech_group"defexport(self)->dict[str,Any]:return{"type":self.type,"input":self.input,}

284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323

classSpeechSpanData(SpanData):"""    Represents a Speech Span in the trace.    Includes input, output, model, model configuration, and first content timestamp.    """__slots__=("input","output","model","model_config","first_content_at")def__init__(self,input:str|None=None,output:str|None=None,output_format:str|None="pcm",model:str|None=None,model_config:Mapping[str,Any]|None=None,first_content_at:str|None=None,):self.input=inputself.output=outputself.output_format=output_formatself.model=modelself.model_config=model_configself.first_content_at=first_content_at@propertydeftype(self)->str:return"speech"defexport(self)->dict[str,Any]:return{"type":self.type,"input":self.input,"output":{"data":self.outputor"","format":self.output_format,},"model":self.model,"model_config":self.model_config,"first_content_at":self.first_content_at,}

240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281

classTranscriptionSpanData(SpanData):"""    Represents a Transcription Span in the trace.    Includes input, output, model, and model configuration.    """__slots__=("input","output","model","model_config",)def__init__(self,input:str|None=None,input_format:str|None="pcm",output:str|None=None,model:str|None=None,model_config:Mapping[str,Any]|None=None,):self.input=inputself.input_format=input_formatself.output=outputself.model=modelself.model_config=model_config@propertydeftype(self)->str:return"transcription"defexport(self)->dict[str,Any]:return{"type":self.type,"input":{"data":self.inputor"","format":self.input_format,},"output":self.output,"model":self.model,"model_config":self.model_config,}

 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 99100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173

classSpan(abc.ABC,Generic[TSpanData]):"""Base class for representing traceable operations with timing and context.    A span represents a single operation within a trace (e.g., an LLM call, tool execution,    or agent run). Spans track timing, relationships between operations, and operation-specific    data.    Type Args:        TSpanData: The type of span-specific data this span contains.    Example:        ```python        # Creating a custom span        with custom_span("database_query", {            "operation": "SELECT",            "table": "users"        }) as span:            results = await db.query("SELECT * FROM users")            span.set_output({"count": len(results)})        # Handling errors in spans        with custom_span("risky_operation") as span:            try:                result = perform_risky_operation()            except Exception as e:                span.set_error({                    "message": str(e),                    "data": {"operation": "risky_operation"}                })                raise        ```        Notes:        - Spans automatically nest under the current trace        - Use context managers for reliable start/finish        - Include relevant data but avoid sensitive information        - Handle errors properly using set_error()    """@property@abc.abstractmethoddeftrace_id(self)->str:"""The ID of the trace this span belongs to.        Returns:            str: Unique identifier of the parent trace.        """pass@property@abc.abstractmethoddefspan_id(self)->str:"""Unique identifier for this span.        Returns:            str: The span's unique ID within its trace.        """pass@property@abc.abstractmethoddefspan_data(self)->TSpanData:"""Operation-specific data for this span.        Returns:            TSpanData: Data specific to this type of span (e.g., LLM generation data).        """pass@abc.abstractmethoddefstart(self,mark_as_current:bool=False):"""        Start the span.        Args:            mark_as_current: If true, the span will be marked as the current span.        """pass@abc.abstractmethoddeffinish(self,reset_current:bool=False)->None:"""        Finish the span.        Args:            reset_current: If true, the span will be reset as the current span.        """pass@abc.abstractmethoddef__enter__(self)->Span[TSpanData]:pass@abc.abstractmethoddef__exit__(self,exc_type,exc_val,exc_tb):pass@property@abc.abstractmethoddefparent_id(self)->str|None:"""ID of the parent span, if any.        Returns:            str | None: The parent span's ID, or None if this is a root span.        """pass@abc.abstractmethoddefset_error(self,error:SpanError)->None:pass@property@abc.abstractmethoddeferror(self)->SpanError|None:"""Any error that occurred during span execution.        Returns:            SpanError | None: Error details if an error occurred, None otherwise.        """pass@abc.abstractmethoddefexport(self)->dict[str,Any]|None:pass@property@abc.abstractmethoddefstarted_at(self)->str|None:"""When the span started execution.        Returns:            str | None: ISO format timestamp of span start, None if not started.        """pass@property@abc.abstractmethoddefended_at(self)->str|None:"""When the span finished execution.        Returns:            str | None: ISO format timestamp of span end, None if not finished.        """pass

18192021222324252627