create¶

AdalFlow tracing creation functions compatible with OpenAI Agents SDK.

This module provides functions to create traces and spans that follow the OpenAI Agents SDK patterns for maximum compatibility with existing tracing backends like MLflow.

References: - OpenAI Agents SDK: https://github.com/openai/openai-agents-python/blob/main/src/agents/tracing/create.py

trace(workflow_name: str, trace_id: str | None = None, group_id: str | None = None, metadata: Dict[str, Any] | None = None, disabled: bool = False) → Trace[source]¶

Create a new trace. The trace will not be started automatically; you should either use it as a context manager (with trace(…):) or call trace.start() + trace.finish() manually.

In addition to the workflow name and optional grouping identifier, you can provide an arbitrary metadata dictionary to attach additional user-defined information to the trace.

Parameters:

workflow_name – The name of the logical app or workflow. For example, you might provide “code_bot” for a coding agent, or “customer_support_agent” for a customer support agent.
trace_id – The ID of the trace. Optional. If not provided, we will generate an ID. We recommend using util.gen_trace_id() to generate a trace ID, to guarantee that IDs are correctly formatted.
group_id – Optional grouping identifier to link multiple traces from the same conversation or process. For instance, you might use a chat thread ID.
metadata – Optional dictionary of additional metadata to attach to the trace.
disabled – If True, we will return a Trace but the Trace will not be recorded. This will not be checked if there’s an existing trace and even_if_trace_running is True.

Returns:

The newly created trace object.

get_current_trace() → Trace | None[source]¶: Returns the currently active trace, if present.

get_current_span() → Span[Any] | None[source]¶: Returns the currently active span, if present.

custom_span(name: str, data: Dict[str, Any] | None = None, span_id: str | None = None, parent: Trace | Span[Any] | None = None, disabled: bool = False) → Span[CustomSpanData][source]¶

Create a new custom span for general-purpose tracing.

This span can be used for any custom tracing needs in AdalFlow workflows. Use this to track custom workflow steps, debug custom components, or add domain-specific tracing information.

Parameters:

name – The name of the custom span.
data – Optional dictionary of custom data to attach to the span.
span_id – The ID of the span. Optional. If not provided, we will generate an ID.
parent – The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.
disabled – If True, we will return a Span but the Span will not be recorded.

Returns:

The newly created custom span.

Create a new AdalFlow runner span for tracing workflow execution.

This span tracks the complete lifecycle of multi-step agent workflows in AdalFlow. Use this to monitor overall workflow performance, track success/failure rates, and analyze step completion patterns.

Parameters:

runner_id – The ID of the runner instance.
max_steps – The maximum number of steps allowed in the workflow.
steps_executed – The number of steps executed so far.
final_answer – The final answer produced by the workflow.
workflow_status – The current status of the workflow (e.g., “running”, “completed”, “failed”).
execution_time – The total execution time in seconds.
span_id – The ID of the span. Optional. If not provided, we will generate an ID.
parent – The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.
disabled – If True, we will return a Span but the Span will not be recorded.

Returns:

The newly created runner span.

Create a new AdalFlow generator span for tracing LLM or model generation.

This span tracks the execution of a generator, such as an LLM call, and captures all relevant context including inputs, outputs, and performance metrics.

Parameters:

generator_id – Unique identifier for the generator instance.
model_kwargs – Parameters used to configure the model.
generator_state_logger – Optional logger for generator state changes.
prompt_kwargs – Input parameters and context for the generation.
prompt_template_with_keywords – The rendered prompt template with keywords filled in.
raw_response – The raw response from the generator.
api_response – The processed response from the API.
generation_time – Time taken for generation in seconds.
token_usage – Dictionary tracking token usage statistics.
final_response – The final response data after any post-processing.
api_kwargs – The API kwargs used for the model call.
span_id – Optional custom span ID. If not provided, one will be generated.
parent – The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.
disabled – If True, we will return a Span but the Span will not be recorded.

Returns:

The newly created generator span.

Create a new AdalFlow tool span for tracing tool/function execution.

This span tracks function calls, tool usage, and external integrations in AdalFlow. Use this to monitor tool performance and reliability, debug tool integration issues, track tool usage patterns, and analyze tool effectiveness in workflows.

Parameters:

tool_name – The name of the tool being executed.
function_name – The specific function name being called.
input_params – The input parameters passed to the tool/function (deprecated, use function_args/function_kwargs).
function_args – The positional arguments passed to the function.
function_kwargs – The keyword arguments passed to the function.
output_result – The result returned by the tool/function.
execution_time – The time taken for execution in seconds.
error_info – Any error information if the tool execution failed.
span_id – The ID of the span. Optional. If not provided, we will generate an ID.
parent – The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.
disabled – If True, we will return a Span but the Span will not be recorded.

Returns:

The newly created tool span.

Create a new AdalFlow response span for tracking final workflow results.

This span tracks the final result of AdalFlow workflows, capturing the output that gets returned to the user. Use this to monitor end-to-end workflow success rates, analyze result quality, and track response patterns.

Parameters:

final_result – The final result produced by the workflow.
result_type – The type of the result (e.g., “string”, “object”, “error”).
execution_metadata – Additional metadata about the execution.
response – The response object (for OpenAI SDK compatibility).
span_id – The ID of the span. Optional. If not provided, we will generate an ID.
parent – The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.
disabled – If True, we will return a Span but the Span will not be recorded.

Returns:

The newly created response span.

Create a new AdalFlow step span for tracking individual workflow steps.

This span tracks individual steps within multi-step agent workflows in AdalFlow. Use this to monitor step-by-step execution, debug workflow logic, track step completion patterns, and analyze individual step performance.

Parameters:

step_number – The step number in the workflow sequence.
action_type – The type of action being performed (e.g., “planning”, “tool_execution”).
observation – The result or observation from this step.
is_final – Whether this is the final step in the workflow.
tool_name – The name of the tool being executed in this step.
tool_output – The output from executing the tool in this step.
execution_time – The time taken to execute this step in seconds.
error_info – Any error information if the step failed.
span_id – The ID of the span. Optional. If not provided, we will generate an ID.
parent – The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.
disabled – If True, we will return a Span but the Span will not be recorded.

Returns:

The newly created step span.