Tracing module

TracingProcessor

Bases: ABC

Interface for processing spans.

Source code in src/cai/sdk/agents/tracing/processor_interface.py

class TracingProcessor(abc.ABC):
    """Interface for processing spans."""

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

        Args:
            trace: The trace that started.
        """
        pass

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

        Args:
            trace: The trace that started.
        """
        pass

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

        Args:
            span: The span that started.
        """
        pass

    @abc.abstractmethod
    def on_span_end(self, span: "Span[Any]") -> None:
        """Called when a span is finished. Should not block or raise exceptions.

        Args:
            span: The span that finished.
        """
        pass

    @abc.abstractmethod
    def shutdown(self) -> None:
        """Called when the application stops."""
        pass

    @abc.abstractmethod
    def force_flush(self) -> None:
        """Forces an immediate flush of all queued spans/traces."""
        pass

on_trace_start abstractmethod

on_trace_start(trace: Trace) -> None

Called when a trace is started.

Parameters:

Name	Type	Description	Default
trace	Trace	The trace that started.	required

Source code in src/cai/sdk/agents/tracing/processor_interface.py

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

    Args:
        trace: The trace that started.
    """
    pass

on_trace_end abstractmethod

on_trace_end(trace: Trace) -> None

Called when a trace is finished.

Parameters:

Name	Type	Description	Default
trace	Trace	The trace that started.	required

Source code in src/cai/sdk/agents/tracing/processor_interface.py

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

    Args:
        trace: The trace that started.
    """
    pass

on_span_start abstractmethod

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

Called when a span is started.

Parameters:

Name	Type	Description	Default
span	Span[Any]	The span that started.	required

Source code in src/cai/sdk/agents/tracing/processor_interface.py

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

    Args:
        span: The span that started.
    """
    pass

on_span_end abstractmethod

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

Called when a span is finished. Should not block or raise exceptions.

Parameters:

Name	Type	Description	Default
span	Span[Any]	The span that finished.	required

Source code in src/cai/sdk/agents/tracing/processor_interface.py

@abc.abstractmethod
def on_span_end(self, span: "Span[Any]") -> None:
    """Called when a span is finished. Should not block or raise exceptions.

    Args:
        span: The span that finished.
    """
    pass

shutdown abstractmethod

shutdown() -> None

Called when the application stops.

Source code in src/cai/sdk/agents/tracing/processor_interface.py

@abc.abstractmethod
def shutdown(self) -> None:
    """Called when the application stops."""
    pass

force_flush abstractmethod

force_flush() -> None

Forces an immediate flush of all queued spans/traces.

Source code in src/cai/sdk/agents/tracing/processor_interface.py

@abc.abstractmethod
def force_flush(self) -> None:
    """Forces an immediate flush of all queued spans/traces."""
    pass

Span

Bases: ABC, Generic[TSpanData]

Source code in src/cai/sdk/agents/tracing/spans.py

class Span(abc.ABC, Generic[TSpanData]):
    @property
    @abc.abstractmethod
    def trace_id(self) -> str:
        pass

    @property
    @abc.abstractmethod
    def span_id(self) -> str:
        pass

    @property
    @abc.abstractmethod
    def span_data(self) -> TSpanData:
        pass

    @abc.abstractmethod
    def start(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.abstractmethod
    def finish(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.abstractmethod
    def __enter__(self) -> Span[TSpanData]:
        pass

    @abc.abstractmethod
    def __exit__(self, exc_type, exc_val, exc_tb):
        pass

    @property
    @abc.abstractmethod
    def parent_id(self) -> str | None:
        pass

    @abc.abstractmethod
    def set_error(self, error: SpanError) -> None:
        pass

    @property
    @abc.abstractmethod
    def error(self) -> SpanError | None:
        pass

    @abc.abstractmethod
    def export(self) -> dict[str, Any] | None:
        pass

    @property
    @abc.abstractmethod
    def started_at(self) -> str | None:
        pass

    @property
    @abc.abstractmethod
    def ended_at(self) -> str | None:
        pass

start abstractmethod

start(mark_as_current: bool = False)

Start the span.

Parameters:

Name	Type	Description	Default
mark_as_current	bool	If true, the span will be marked as the current span.	False

Source code in src/cai/sdk/agents/tracing/spans.py

@abc.abstractmethod
def start(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

finish abstractmethod

finish(reset_current: bool = False) -> None

Finish the span.

Parameters:

Name	Type	Description	Default
reset_current	bool	If true, the span will be reset as the current span.	False

Source code in src/cai/sdk/agents/tracing/spans.py

@abc.abstractmethod
def finish(self, reset_current: bool = False) -> None:
    """
    Finish the span.

    Args:
        reset_current: If true, the span will be reset as the current span.
    """
    pass

Trace

A trace is the root level object that tracing creates. It represents a logical "workflow".

Source code in src/cai/sdk/agents/tracing/traces.py

class Trace:
    """
    A trace is the root level object that tracing creates. It represents a logical "workflow".
    """

    @abc.abstractmethod
    def __enter__(self) -> Trace:
        pass

    @abc.abstractmethod
    def __exit__(self, exc_type, exc_val, exc_tb):
        pass

    @abc.abstractmethod
    def start(self, mark_as_current: bool = False):
        """
        Start the trace.

        Args:
            mark_as_current: If true, the trace will be marked as the current trace.
        """
        pass

    @abc.abstractmethod
    def finish(self, reset_current: bool = False):
        """
        Finish the trace.

        Args:
            reset_current: If true, the trace will be reset as the current trace.
        """
        pass

    @property
    @abc.abstractmethod
    def trace_id(self) -> str:
        """
        The trace ID.
        """
        pass

    @property
    @abc.abstractmethod
    def name(self) -> str:
        """
        The name of the workflow being traced.
        """
        pass

    @abc.abstractmethod
    def export(self) -> dict[str, Any] | None:
        """
        Export the trace as a dictionary.
        """
        pass

trace_id abstractmethod property

trace_id: str

The trace ID.

name abstractmethod property

name: str

The name of the workflow being traced.

start abstractmethod

start(mark_as_current: bool = False)

Start the trace.

Parameters:

Name	Type	Description	Default
mark_as_current	bool	If true, the trace will be marked as the current trace.	False

Source code in src/cai/sdk/agents/tracing/traces.py

@abc.abstractmethod
def start(self, mark_as_current: bool = False):
    """
    Start the trace.

    Args:
        mark_as_current: If true, the trace will be marked as the current trace.
    """
    pass

finish abstractmethod

finish(reset_current: bool = False)

Finish the trace.

Parameters:

Name	Type	Description	Default
reset_current	bool	If true, the trace will be reset as the current trace.	False

Source code in src/cai/sdk/agents/tracing/traces.py

@abc.abstractmethod
def finish(self, reset_current: bool = False):
    """
    Finish the trace.

    Args:
        reset_current: If true, the trace will be reset as the current trace.
    """
    pass

export abstractmethod

export() -> dict[str, Any] | None

Export the trace as a dictionary.

Source code in src/cai/sdk/agents/tracing/traces.py

@abc.abstractmethod
def export(self) -> dict[str, Any] | None:
    """
    Export the trace as a dictionary.
    """
    pass

agent_span

agent_span(
    name: str,
    handoffs: list[str] | None = None,
    tools: list[str] | None = None,
    output_type: str | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[AgentSpanData]

Create a new agent span. The span will not be started automatically, you should either do with agent_span() ... or call span.start() + span.finish() manually.

Parameters:

Name	Type	Description	Default
name	str	The name of the agent.	required
handoffs	list[str] | None	Optional list of agent names to which this agent could hand off control.	None
tools	list[str] | None	Optional list of tool names available to this agent.	None
output_type	str | None	Optional name of the output type produced by the agent.	None
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Returns:

Type	Description
Span[AgentSpanData]	The newly created agent span.

Source code in src/cai/sdk/agents/tracing/create.py

def agent_span(
    name: str,
    handoffs: list[str] | None = None,
    tools: list[str] | None = None,
    output_type: str | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[AgentSpanData]:
    """Create a new agent span. The span will not be started automatically, you should either do
    `with agent_span() ...` or call `span.start()` + `span.finish()` manually.

    Args:
        name: The name of the agent.
        handoffs: Optional list of agent names to which this agent could hand off control.
        tools: Optional list of tool names available to this agent.
        output_type: Optional name of the output type produced by the agent.
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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 agent span.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=AgentSpanData(name=name, handoffs=handoffs, tools=tools, output_type=output_type),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

custom_span

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]

Create a new custom span, to which you can add your own metadata. The span will not be started automatically, you should either do with custom_span() ... or call span.start() + span.finish() manually.

Parameters:

Name	Type	Description	Default
name	str	The name of the custom span.	required
data	dict[str, Any] | None	Arbitrary structured data to associate with the span.	None
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Returns:

Type	Description
Span[CustomSpanData]	The newly created custom span.

Source code in src/cai/sdk/agents/tracing/create.py

def 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]:
    """Create a new custom span, to which you can add your own metadata. The span will not be
    started automatically, you should either do `with custom_span() ...` or call
    `span.start()` + `span.finish()` manually.

    Args:
        name: The name of the custom span.
        data: Arbitrary structured data to associate with the span.
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=CustomSpanData(name=name, data=data or {}),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

function_span

function_span(
    name: str,
    input: str | None = None,
    output: str | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[FunctionSpanData]

Create a new function span. The span will not be started automatically, you should either do with function_span() ... or call span.start() + span.finish() manually.

Parameters:

Name	Type	Description	Default
name	str	The name of the function.	required
input	str | None	The input to the function.	None
output	str | None	The output of the function.	None
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Returns:

Type	Description
Span[FunctionSpanData]	The newly created function span.

Source code in src/cai/sdk/agents/tracing/create.py

def function_span(
    name: str,
    input: str | None = None,
    output: str | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[FunctionSpanData]:
    """Create a new function span. The span will not be started automatically, you should either do
    `with function_span() ...` or call `span.start()` + `span.finish()` manually.

    Args:
        name: The name of the function.
        input: The input to the function.
        output: The output of the function.
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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 function span.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=FunctionSpanData(name=name, input=input, output=output),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

generation_span

generation_span(
    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,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[GenerationSpanData]

Create a new generation span. The span will not be started automatically, you should either do with generation_span() ... or call span.start() + span.finish() manually.

This span captures the details of a model generation, including the input message sequence, any generated outputs, the model name and configuration, and usage data. If you only need to capture a model response identifier, use response_span() instead.

Parameters:

Name	Type	Description	Default
input	Sequence[Mapping[str, Any]] | None	The sequence of input messages sent to the model.	None
output	Sequence[Mapping[str, Any]] | None	The sequence of output messages received from the model.	None
model	str | None	The model identifier used for the generation.	None
model_config	Mapping[str, Any] | None	The model configuration (hyperparameters) used.	None
usage	dict[str, Any] | None	A dictionary of usage information (input tokens, output tokens, etc.).	None
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Returns:

Type	Description
Span[GenerationSpanData]	The newly created generation span.

Source code in src/cai/sdk/agents/tracing/create.py

def generation_span(
    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,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[GenerationSpanData]:
    """Create a new generation span. The span will not be started automatically, you should either
    do `with generation_span() ...` or call `span.start()` + `span.finish()` manually.

    This span captures the details of a model generation, including the
    input message sequence, any generated outputs, the model name and
    configuration, and usage data. If you only need to capture a model
    response identifier, use `response_span()` instead.

    Args:
        input: The sequence of input messages sent to the model.
        output: The sequence of output messages received from the model.
        model: The model identifier used for the generation.
        model_config: The model configuration (hyperparameters) used.
        usage: A dictionary of usage information (input tokens, output tokens, etc.).
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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 generation span.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=GenerationSpanData(
            input=input,
            output=output,
            model=model,
            model_config=model_config,
            usage=usage,
        ),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

get_current_span

get_current_span() -> Span[Any] | None

Returns the currently active span, if present.

Source code in src/cai/sdk/agents/tracing/create.py

def get_current_span() -> Span[Any] | None:
    """Returns the currently active span, if present."""
    return GLOBAL_TRACE_PROVIDER.get_current_span()

get_current_trace

get_current_trace() -> Trace | None

Returns the currently active trace, if present.

Source code in src/cai/sdk/agents/tracing/create.py

def get_current_trace() -> Trace | None:
    """Returns the currently active trace, if present."""
    return GLOBAL_TRACE_PROVIDER.get_current_trace()

guardrail_span

guardrail_span(
    name: str,
    triggered: bool = False,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[GuardrailSpanData]

Create a new guardrail span. The span will not be started automatically, you should either do with guardrail_span() ... or call span.start() + span.finish() manually.

Parameters:

Name	Type	Description	Default
name	str	The name of the guardrail.	required
triggered	bool	Whether the guardrail was triggered.	False
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Source code in src/cai/sdk/agents/tracing/create.py

def guardrail_span(
    name: str,
    triggered: bool = False,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[GuardrailSpanData]:
    """Create a new guardrail span. The span will not be started automatically, you should either
    do `with guardrail_span() ...` or call `span.start()` + `span.finish()` manually.

    Args:
        name: The name of the guardrail.
        triggered: Whether the guardrail was triggered.
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=GuardrailSpanData(name=name, triggered=triggered),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

handoff_span

handoff_span(
    from_agent: str | None = None,
    to_agent: str | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[HandoffSpanData]

Create a new handoff span. The span will not be started automatically, you should either do with handoff_span() ... or call span.start() + span.finish() manually.

Parameters:

Name	Type	Description	Default
from_agent	str | None	The name of the agent that is handing off.	None
to_agent	str | None	The name of the agent that is receiving the handoff.	None
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Returns:

Type	Description
Span[HandoffSpanData]	The newly created handoff span.

Source code in src/cai/sdk/agents/tracing/create.py

def handoff_span(
    from_agent: str | None = None,
    to_agent: str | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[HandoffSpanData]:
    """Create a new handoff span. The span will not be started automatically, you should either do
    `with handoff_span() ...` or call `span.start()` + `span.finish()` manually.

    Args:
        from_agent: The name of the agent that is handing off.
        to_agent: The name of the agent that is receiving the handoff.
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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 handoff span.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=HandoffSpanData(from_agent=from_agent, to_agent=to_agent),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

mcp_tools_span

mcp_tools_span(
    server: str | None = None,
    result: list[str] | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[MCPListToolsSpanData]

Create a new MCP list tools span. The span will not be started automatically, you should either do with mcp_tools_span() ... or call span.start() + span.finish() manually.

Parameters:

Name	Type	Description	Default
server	str | None	The name of the MCP server.	None
result	list[str] | None	The result of the MCP list tools call.	None
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Source code in src/cai/sdk/agents/tracing/create.py

def mcp_tools_span(
    server: str | None = None,
    result: list[str] | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[MCPListToolsSpanData]:
    """Create a new MCP list tools span. The span will not be started automatically, you should
    either do `with mcp_tools_span() ...` or call `span.start()` + `span.finish()` manually.

    Args:
        server: The name of the MCP server.
        result: The result of the MCP list tools call.
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=MCPListToolsSpanData(server=server, result=result),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

response_span

response_span(
    response: Response | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[ResponseSpanData]

Create a new response span. The span will not be started automatically, you should either do with response_span() ... or call span.start() + span.finish() manually.

Parameters:

Name	Type	Description	Default
response	Response | None	The OpenAI Response object.	None
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Source code in src/cai/sdk/agents/tracing/create.py

def response_span(
    response: Response | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[ResponseSpanData]:
    """Create a new response span. The span will not be started automatically, you should either do
    `with response_span() ...` or call `span.start()` + `span.finish()` manually.

    Args:
        response: The OpenAI Response object.
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=ResponseSpanData(response=response),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

speech_group_span

speech_group_span(
    input: str | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[SpeechGroupSpanData]

Create a new speech group span. The span will not be started automatically, you should either do with speech_group_span() ... or call span.start() + span.finish() manually.

Parameters:

Name	Type	Description	Default
input	str | None	The input text used for the speech request.	None
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Source code in src/cai/sdk/agents/tracing/create.py

def speech_group_span(
    input: str | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[SpeechGroupSpanData]:
    """Create a new speech group span. The span will not be started automatically, you should
    either do `with speech_group_span() ...` or call `span.start()` + `span.finish()` manually.

    Args:
        input: The input text used for the speech request.
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=SpeechGroupSpanData(input=input),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

speech_span

speech_span(
    model: str | None = None,
    input: str | None = None,
    output: str | None = None,
    output_format: str | None = "pcm",
    model_config: Mapping[str, Any] | None = None,
    first_content_at: str | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[SpeechSpanData]

Create a new speech span. The span will not be started automatically, you should either do with speech_span() ... or call span.start() + span.finish() manually.

Parameters:

Name	Type	Description	Default
model	str | None	The name of the model used for the text-to-speech.	None
input	str | None	The text input of the text-to-speech.	None
output	str | None	The audio output of the text-to-speech as base64 encoded string of PCM audio bytes.	None
output_format	str | None	The format of the audio output (defaults to "pcm").	'pcm'
model_config	Mapping[str, Any] | None	The model configuration (hyperparameters) used.	None
first_content_at	str | None	The time of the first byte of the audio output.	None
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Source code in src/cai/sdk/agents/tracing/create.py

def speech_span(
    model: str | None = None,
    input: str | None = None,
    output: str | None = None,
    output_format: str | None = "pcm",
    model_config: Mapping[str, Any] | None = None,
    first_content_at: str | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[SpeechSpanData]:
    """Create a new speech span. The span will not be started automatically, you should either do
    `with speech_span() ...` or call `span.start()` + `span.finish()` manually.

    Args:
        model: The name of the model used for the text-to-speech.
        input: The text input of the text-to-speech.
        output: The audio output of the text-to-speech as base64 encoded string of PCM audio bytes.
        output_format: The format of the audio output (defaults to "pcm").
        model_config: The model configuration (hyperparameters) used.
        first_content_at: The time of the first byte of the audio output.
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=SpeechSpanData(
            model=model,
            input=input,
            output=output,
            output_format=output_format,
            model_config=model_config,
            first_content_at=first_content_at,
        ),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

trace

trace(
    workflow_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. 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:

Name	Type	Description	Default
workflow_name	str	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.	required
trace_id	str | None	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.	None
group_id	str | None	Optional grouping identifier to link multiple traces from the same conversation or process. For instance, you might use a chat thread ID.	None
metadata	dict[str, Any] | None	Optional dictionary of additional metadata to attach to the trace.	None
disabled	bool	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.	False

Returns:

Type	Description
Trace	The newly created trace object.

Source code in src/cai/sdk/agents/tracing/create.py

def trace(
    workflow_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. 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.

    Args:
        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.
    """
    current_trace = GLOBAL_TRACE_PROVIDER.get_current_trace()
    if current_trace:
        logger.warning(
            "Trace already exists. Creating a new trace, but this is probably a mistake."
        )

    return GLOBAL_TRACE_PROVIDER.create_trace(
        name=workflow_name,
        trace_id=trace_id,
        group_id=group_id,
        metadata=metadata,
        disabled=disabled,
    )

transcription_span

transcription_span(
    model: str | None = None,
    input: str | None = None,
    input_format: str | None = "pcm",
    output: str | None = None,
    model_config: Mapping[str, Any] | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[TranscriptionSpanData]

Create a new transcription span. The span will not be started automatically, you should either do with transcription_span() ... or call span.start() + span.finish() manually.

Parameters:

Name	Type	Description	Default
model	str | None	The name of the model used for the speech-to-text.	None
input	str | None	The audio input of the speech-to-text transcription, as a base64 encoded string of audio bytes.	None
input_format	str | None	The format of the audio input (defaults to "pcm").	'pcm'
output	str | None	The output of the speech-to-text transcription.	None
model_config	Mapping[str, Any] | None	The model configuration (hyperparameters) used.	None
span_id	str | None	The ID of the span. Optional. If not provided, we will generate an ID. We recommend using util.gen_span_id() to generate a span ID, to guarantee that IDs are correctly formatted.	None
parent	Trace | Span[Any] | None	The parent span or trace. If not provided, we will automatically use the current trace/span as the parent.	None
disabled	bool	If True, we will return a Span but the Span will not be recorded.	False

Returns:

Type	Description
Span[TranscriptionSpanData]	The newly created speech-to-text span.

Source code in src/cai/sdk/agents/tracing/create.py

def transcription_span(
    model: str | None = None,
    input: str | None = None,
    input_format: str | None = "pcm",
    output: str | None = None,
    model_config: Mapping[str, Any] | None = None,
    span_id: str | None = None,
    parent: Trace | Span[Any] | None = None,
    disabled: bool = False,
) -> Span[TranscriptionSpanData]:
    """Create a new transcription span. The span will not be started automatically, you should
    either do `with transcription_span() ...` or call `span.start()` + `span.finish()` manually.

    Args:
        model: The name of the model used for the speech-to-text.
        input: The audio input of the speech-to-text transcription, as a base64 encoded string of
            audio bytes.
        input_format: The format of the audio input (defaults to "pcm").
        output: The output of the speech-to-text transcription.
        model_config: The model configuration (hyperparameters) used.
        span_id: The ID of the span. Optional. If not provided, we will generate an ID. We
            recommend using `util.gen_span_id()` to generate a span ID, to guarantee that IDs are
            correctly formatted.
        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 speech-to-text span.
    """
    return GLOBAL_TRACE_PROVIDER.create_span(
        span_data=TranscriptionSpanData(
            input=input,
            input_format=input_format,
            output=output,
            model=model,
            model_config=model_config,
        ),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

gen_span_id

gen_span_id() -> str

Generates a new span ID.

Source code in src/cai/sdk/agents/tracing/util.py

def gen_span_id() -> str:
    """Generates a new span ID."""
    return f"span_{uuid.uuid4().hex[:24]}"

gen_trace_id

gen_trace_id() -> str

Generates a new trace ID.

Source code in src/cai/sdk/agents/tracing/util.py

def gen_trace_id() -> str:
    """Generates a new trace ID."""
    return f"trace_{uuid.uuid4().hex}"

add_trace_processor

add_trace_processor(
    span_processor: TracingProcessor,
) -> None

Adds a new trace processor. This processor will receive all traces/spans.

Source code in src/cai/sdk/agents/tracing/__init__.py

def add_trace_processor(span_processor: TracingProcessor) -> None:
    """
    Adds a new trace processor. This processor will receive all traces/spans.
    """
    GLOBAL_TRACE_PROVIDER.register_processor(span_processor)

set_trace_processors

set_trace_processors(
    processors: list[TracingProcessor],
) -> None

Set the list of trace processors. This will replace the current list of processors.

Source code in src/cai/sdk/agents/tracing/__init__.py

def set_trace_processors(processors: list[TracingProcessor]) -> None:
    """
    Set the list of trace processors. This will replace the current list of processors.
    """
    GLOBAL_TRACE_PROVIDER.set_processors(processors)

set_tracing_disabled

set_tracing_disabled(disabled: bool) -> None

Set whether tracing is globally disabled.

Source code in src/cai/sdk/agents/tracing/__init__.py

def set_tracing_disabled(disabled: bool) -> None:
    """
    Set whether tracing is globally disabled.
    """
    GLOBAL_TRACE_PROVIDER.set_disabled(disabled)

set_tracing_export_api_key

set_tracing_export_api_key(api_key: str) -> None

Set the OpenAI API key for the backend exporter.

Source code in src/cai/sdk/agents/tracing/__init__.py

def set_tracing_export_api_key(api_key: str) -> None:
    """
    Set the OpenAI API key for the backend exporter.
    """
    default_exporter().set_api_key(api_key)