创建追踪/跨度

trace

trace(
    workflow_name: str,
    trace_id: str | None = None,
    group_id: str | None = None,
    metadata: dict[str, Any] | None = None,
    tracing: TracingConfig | None = None,
    disabled: bool = False,
) -> Trace

创建一个新的追踪。追踪不会自动启动；您应该使用它作为上下文管理器（with trace(...):）或手动调用 trace.start() + trace.finish()。

除了工作流名称和可选的分组标识符之外，您还可以提供一个任意的元数据字典，以附加额外的用户定义信息到追踪。

参数

名称	类型	描述	默认
workflow_name	str	逻辑应用程序或工作流的名称。例如，您可以为编码代理提供“code_bot”，或为客户支持代理提供“customer_support_agent”。	required
trace_id	str | None	追踪的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_trace_id() 生成追踪 ID，以保证 ID 正确格式化。	None
group_id	str | None	可选的分组标识符，用于链接来自同一对话或流程的多个追踪。例如，您可以使用聊天线程 ID。	None
metadata	dict[str, Any] | None	可选的附加元数据字典，用于附加到追踪。	None
追踪	TracingConfig | None	用于导出此追踪的可选追踪配置。	None
disabled	bool	如果为 True，我们将返回一个 Trace，但该 Trace 不会被记录。	False

返回值

类型	描述
Trace	新创建的追踪对象。

源代码在 src/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,
    tracing: TracingConfig | 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.
        tracing: Optional tracing configuration for exporting this trace.
        disabled: If True, we will return a Trace but the Trace will not be recorded.

    Returns:
        The newly created trace object.
    """
    current_trace = get_trace_provider().get_current_trace()
    if current_trace:
        logger.warning(
            "Trace already exists. Creating a new trace, but this is probably a mistake."
        )

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

get_current_trace

get_current_trace() -> Trace | None

返回当前活动的追踪（如果存在）。

源代码在 src/agents/tracing/create.py

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

get_current_span

get_current_span() -> Span[Any] | None

返回当前活动的跨度（如果存在）。

源代码在 src/agents/tracing/create.py

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

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]

创建一个新的 agent 跨度。跨度不会自动启动，您应该使用 with agent_span() ... 或手动调用 span.start() + span.finish()。

参数

名称	类型	描述	默认
name	str	代理的名称。	required
handoffs	list[str] | None	可选的 agent 名称列表，该 agent 可以将控制权移交给这些 agent。	None
工具	list[str] | None	可选的 agent 可用的工具名称列表。	None
output_type	str | None	可选的 agent 产生的输出类型名称。	None
span_id	str | None	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

返回值

类型	描述
Span[AgentSpanData]	新创建的 agent span。

源代码在 src/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 get_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,
    )

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]

创建一个新的函数跨度。跨度不会自动启动，您应该使用 with function_span() ... 或手动调用 span.start() + span.finish()。

参数

名称	类型	描述	默认
name	str	函数的名称。	required
input	str | None	函数的输入。	None
output	str | None	函数的输出。	None
span_id	str | None	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

返回值

类型	描述
Span[FunctionSpanData]	新创建的函数跨度。

源代码在 src/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 get_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]

创建一个新的生成跨度。跨度不会自动启动，您应该使用 with generation_span() ... 或手动调用 span.start() + span.finish()。

此跨度捕获模型的生成细节，包括输入消息序列、任何生成的输出、模型名称和配置以及使用数据。如果您只需要捕获模型响应标识符，请使用 response_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	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

返回值

类型	描述
Span[GenerationSpanData]	新创建的生成跨度。

源代码在 src/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 get_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,
    )

response_span

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

创建一个新的响应跨度。跨度不会自动启动，您应该使用 with response_span() ... 或手动调用 span.start() + span.finish()。

参数

名称	类型	描述	默认
response	Response | None	OpenAI 响应对象。	None
span_id	str | None	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

源代码在 src/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 get_trace_provider().create_span(
        span_data=ResponseSpanData(response=response),
        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]

创建一个新的交接跨度。跨度不会自动启动，您应该使用 with handoff_span() ... 或手动调用 span.start() + span.finish()。

参数

名称	类型	描述	默认
来自 Agent	str | None	交接的 agent 的名称。	None
前往 Agent	str | None	接收交接的 agent 的名称。	None
span_id	str | None	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

返回值

类型	描述
Span[HandoffSpanData]	新创建的 handoff span。

源代码在 src/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 get_trace_provider().create_span(
        span_data=HandoffSpanData(from_agent=from_agent, to_agent=to_agent),
        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]

创建一个新的自定义跨度，您可以向其添加自己的元数据。跨度不会自动启动，您应该使用 with custom_span() ... 或手动调用 span.start() + span.finish()。

参数

名称	类型	描述	默认
name	str	自定义跨度的名称。	required
data	dict[str, Any] | None	与跨度关联的任意结构化数据。	None
span_id	str | None	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

返回值

类型	描述
Span[CustomSpanData]	新创建的自定义跨度。

源代码在 src/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 get_trace_provider().create_span(
        span_data=CustomSpanData(name=name, data=data or {}),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )

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]

创建一个新的 guardrail 跨度。跨度不会自动启动，您应该使用 with guardrail_span() ... 或手动调用 span.start() + span.finish()。

参数

名称	类型	描述	默认
name	str	防护栏的名称。	required
triggered	bool	guardrail 是否被触发。	False
span_id	str | None	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

源代码在 src/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 get_trace_provider().create_span(
        span_data=GuardrailSpanData(name=name, triggered=triggered),
        span_id=span_id,
        parent=parent,
        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]

创建一个新的转录跨度。跨度不会自动启动，您应该使用 with transcription_span() ... 或手动调用 span.start() + span.finish()。

参数

名称	类型	描述	默认
model	str | None	用于语音到文本的模型的名称。	None
input	str | None	语音到文本转录的音频输入，为 base64 编码的音频字节字符串。	None
input_format	str | None	音频输入的格式（默认为“pcm”）。	'pcm'
output	str | None	语音到文本转录的输出。	None
model_config	Mapping[str, Any] | None	使用的模型配置（超参数）。	None
span_id	str | None	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

返回值

类型	描述
Span[TranscriptionSpanData]	新创建的语音到文本跨度。

源代码在 src/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 get_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,
    )

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]

创建一个新的语音跨度。跨度不会自动启动，您应该使用 with speech_span() ... 或手动调用 span.start() + span.finish()。

参数

名称	类型	描述	默认
model	str | None	用于文本到语音的模型的名称。	None
input	str | None	文本到语音的文本输入。	None
output	str | None	文本到语音的音频输出，为 base64 编码的 PCM 音频字节字符串。	None
output_format	str | None	音频输出的格式（默认为“pcm”）。	'pcm'
model_config	Mapping[str, Any] | None	使用的模型配置（超参数）。	None
first_content_at	str | None	音频输出的第一个字节的时间。	None
span_id	str | None	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

源代码在 src/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 get_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,
    )

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]

创建一个新的语音组跨度。跨度不会自动启动，您应该使用 with speech_group_span() ... 或手动调用 span.start() + span.finish()。

参数

名称	类型	描述	默认
input	str | None	用于语音请求的输入文本。	None
span_id	str | None	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

源代码在 src/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 get_trace_provider().create_span(
        span_data=SpeechGroupSpanData(input=input),
        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]

创建一个新的 MCP list tools 跨度。跨度不会自动启动，您应该使用 with mcp_tools_span() ... 或手动调用 span.start() + span.finish()。

参数

名称	类型	描述	默认
server	str | None	MCP 服务器的名称。	None
result	list[str] | None	MCP list tools 调用结果。	None
span_id	str | None	跨度的 ID。可选。如果未提供，我们将生成一个 ID。我们建议使用 util.gen_span_id() 生成跨度 ID，以保证 ID 正确格式化。	None
parent	Trace | Span[Any] | None	父跨度或追踪。如果未提供，我们将自动使用当前追踪/跨度作为父级。	None
disabled	bool	如果为 True，我们将返回一个 Span，但该 Span 不会被记录。	False

源代码在 src/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 get_trace_provider().create_span(
        span_data=MCPListToolsSpanData(server=server, result=result),
        span_id=span_id,
        parent=parent,
        disabled=disabled,
    )