Span data

SpanData

Bases: ABC

表示 trace 中的 span 数据。

Source code in agents/tracing/span_data.py

class SpanData(abc.ABC):
    """
    表示 trace 中的 span 数据。
    """

    @abc.abstractmethod
    def export(self) -> dict[str, Any]:
        """以字典形式导出 span 数据。"""
        pass

    @property
    @abc.abstractmethod
    def type(self) -> str:
        """返回 span 的类型。"""
        pass

type abstractmethod property

type: str

返回 span 的类型。

export abstractmethod

export() -> dict[str, Any]

以字典形式导出 span 数据。

Source code in agents/tracing/span_data.py

@abc.abstractmethod
def export(self) -> dict[str, Any]:
    """以字典形式导出 span 数据。"""
    pass

AgentSpanData

Bases: SpanData

表示 trace 中的 Agent Span。 包含 name、handoffs、tools 和 output_type。

Source code in agents/tracing/span_data.py

class AgentSpanData(SpanData):
    """
    表示 trace 中的 Agent Span。
    包含 name、handoffs、tools 和 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 = name
        self.handoffs: list[str] | None = handoffs
        self.tools: list[str] | None = tools
        self.output_type: str | None = output_type

    @property
    def type(self) -> str:
        return "agent"

    def export(self) -> dict[str, Any]:
        return {
            "type": self.type,
            "name": self.name,
            "handoffs": self.handoffs,
            "tools": self.tools,
            "output_type": self.output_type,
        }

FunctionSpanData

Bases: SpanData

表示 trace 中的 Function Span。 包含 input、output 以及 MCP 数据（如适用）。

Source code in agents/tracing/span_data.py

class FunctionSpanData(SpanData):
    """
    表示 trace 中的 Function Span。
    包含 input、output 以及 MCP 数据（如适用）。
    """

    __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 = name
        self.input = input
        self.output = output
        self.mcp_data = mcp_data

    @property
    def type(self) -> str:
        return "function"

    def export(self) -> dict[str, Any]:
        return {
            "type": self.type,
            "name": self.name,
            "input": self.input,
            "output": str(self.output) if self.output else None,
            "mcp_data": self.mcp_data,
        }

GenerationSpanData

Bases: SpanData

表示 trace 中的 Generation Span。 包含 input、output、model、model_config 和 usage。

Source code in agents/tracing/span_data.py

class GenerationSpanData(SpanData):
    """
    表示 trace 中的 Generation Span。
    包含 input、output、model、model_config 和 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 = input
        self.output = output
        self.model = model
        self.model_config = model_config
        self.usage = usage

    @property
    def type(self) -> str:
        return "generation"

    def export(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,
        }

ResponseSpanData

Bases: SpanData

表示 trace 中的 Response Span。 包含 response 和 input。

Source code in agents/tracing/span_data.py

class ResponseSpanData(SpanData):
    """
    表示 trace 中的 Response Span。
    包含 response 和 input。
    """

    __slots__ = ("response", "input")

    def __init__(
        self,
        response: Response | None = None,
        input: str | list[ResponseInputItemParam] | None = None,
    ) -> None:
        self.response = response
        # 这不会被 OpenAI 的 trace 处理器使用，但对其他追踪处理器实现很有用
        self.input = input

    @property
    def type(self) -> str:
        return "response"

    def export(self) -> dict[str, Any]:
        return {
            "type": self.type,
            "response_id": self.response.id if self.response else None,
        }

HandoffSpanData

Bases: SpanData

表示 trace 中的 Handoff Span。 包含源 agent 和目标 agent。

Source code in agents/tracing/span_data.py

class HandoffSpanData(SpanData):
    """
    表示 trace 中的 Handoff Span。
    包含源 agent 和目标 agent。
    """

    __slots__ = ("from_agent", "to_agent")

    def __init__(self, from_agent: str | None, to_agent: str | None):
        self.from_agent = from_agent
        self.to_agent = to_agent

    @property
    def type(self) -> str:
        return "handoff"

    def export(self) -> dict[str, Any]:
        return {
            "type": self.type,
            "from_agent": self.from_agent,
            "to_agent": self.to_agent,
        }

CustomSpanData

Bases: SpanData

表示 trace 中的 Custom Span。 包含 name 和 data 属性包。

Source code in agents/tracing/span_data.py

class CustomSpanData(SpanData):
    """
    表示 trace 中的 Custom Span。
    包含 name 和 data 属性包。
    """

    __slots__ = ("name", "data")

    def __init__(self, name: str, data: dict[str, Any]):
        self.name = name
        self.data = data

    @property
    def type(self) -> str:
        return "custom"

    def export(self) -> dict[str, Any]:
        return {
            "type": self.type,
            "name": self.name,
            "data": self.data,
        }

GuardrailSpanData

Bases: SpanData

表示 trace 中的 Guardrail Span。 包含 name 和 triggered 状态。

Source code in agents/tracing/span_data.py

class GuardrailSpanData(SpanData):
    """
    表示 trace 中的 Guardrail Span。
    包含 name 和 triggered 状态。
    """

    __slots__ = ("name", "triggered")

    def __init__(self, name: str, triggered: bool = False):
        self.name = name
        self.triggered = triggered

    @property
    def type(self) -> str:
        return "guardrail"

    def export(self) -> dict[str, Any]:
        return {
            "type": self.type,
            "name": self.name,
            "triggered": self.triggered,
        }

TranscriptionSpanData

Bases: SpanData

表示 trace 中的 Transcription Span。 包含 input、output、model 和 model_config。

Source code in agents/tracing/span_data.py

class TranscriptionSpanData(SpanData):
    """
    表示 trace 中的 Transcription Span。
    包含 input、output、model 和 model_config。
    """

    __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 = input
        self.input_format = input_format
        self.output = output
        self.model = model
        self.model_config = model_config

    @property
    def type(self) -> str:
        return "transcription"

    def export(self) -> dict[str, Any]:
        return {
            "type": self.type,
            "input": {
                "data": self.input or "",
                "format": self.input_format,
            },
            "output": self.output,
            "model": self.model,
            "model_config": self.model_config,
        }

SpeechSpanData

Bases: SpanData

表示 trace 中的 Speech Span。 包含 input、output、model、model_config 和 first_content_at。

Source code in agents/tracing/span_data.py

class SpeechSpanData(SpanData):
    """
    表示 trace 中的 Speech Span。
    包含 input、output、model、model_config 和 first_content_at。
    """

    __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 = input
        self.output = output
        self.output_format = output_format
        self.model = model
        self.model_config = model_config
        self.first_content_at = first_content_at

    @property
    def type(self) -> str:
        return "speech"

    def export(self) -> dict[str, Any]:
        return {
            "type": self.type,
            "input": self.input,
            "output": {
                "data": self.output or "",
                "format": self.output_format,
            },
            "model": self.model,
            "model_config": self.model_config,
            "first_content_at": self.first_content_at,
        }

SpeechGroupSpanData

Bases: SpanData

表示 trace 中的 Speech Group Span。

Source code in agents/tracing/span_data.py

class SpeechGroupSpanData(SpanData):
    """
    表示 trace 中的 Speech Group Span。
    """

    __slots__ = "input"

    def __init__(
        self,
        input: str | None = None,
    ):
        self.input = input

    @property
    def type(self) -> str:
        return "speech_group"

    def export(self) -> dict[str, Any]:
        return {
            "type": self.type,
            "input": self.input,
        }

MCPListToolsSpanData

Bases: SpanData

表示 trace 中的 MCP List Tools Span。 包含 server 和 result。

Source code in agents/tracing/span_data.py

class MCPListToolsSpanData(SpanData):
    """
    表示 trace 中的 MCP List Tools Span。
    包含 server 和 result。
    """

    __slots__ = (
        "server",
        "result",
    )

    def __init__(self, server: str | None = None, result: list[str] | None = None):
        self.server = server
        self.result = result

    @property
    def type(self) -> str:
        return "mcp_tools"

    def export(self) -> dict[str, Any]:
        return {
            "type": self.type,
            "server": self.server,
            "result": self.result,
        }