追踪

Agents SDK 包含内置追踪功能，收集代理运行期间的全面事件记录：LLM 生成、工具调用、交接、防护栏，甚至自定义事件。使用追踪仪表板，您可以在开发和生产期间调试、可视化和监控您的工作流程。

注意

默认情况下已启用追踪。有两种方法可以禁用追踪

您可以通过设置环境变量 OPENAI_AGENTS_DISABLE_TRACING=1 来全局禁用追踪
您可以通过将 agents.run.RunConfig.tracing_disabled 设置为 True 来禁用单个运行的追踪

对于使用 OpenAI API 且遵循零数据保留 (ZDR) 策略的组织，追踪不可用。

追踪和跨度

追踪代表一个“工作流程”的单个端到端操作。它们由跨度组成。追踪具有以下属性
- workflow_name：这是逻辑工作流程或应用程序。例如“代码生成”或“客户服务”。
- trace_id：追踪的唯一 ID。如果您不传递 ID，则自动生成。必须采用 trace_<32_alphanumeric> 格式。
- group_id：可选的组 ID，用于链接来自同一对话的多个追踪。例如，您可以使用聊天线程 ID。
- disabled：如果为 True，则不会记录追踪。
- metadata：追踪的可选元数据。
跨度代表具有开始和结束时间的运行。跨度具有
- started_at 和 ended_at 时间戳。
- trace_id，表示它们所属的追踪
- parent_id，指向此跨度的父跨度（如果有的话）
- span_data，这是关于跨度的信息。例如，AgentSpanData 包含关于代理的信息，GenerationSpanData 包含关于 LLM 生成的信息，等等。

默认追踪

默认情况下，SDK 追踪以下内容

整个 Runner.{run, run_sync, run_streamed}() 都包含在 trace() 中。
每次代理运行时，它都会被包含在 agent_span() 中
LLM 生成被包含在 generation_span() 中
函数工具调用每个都被包含在 function_span() 中
防护栏被包含在 guardrail_span() 中
交接被包含在 handoff_span() 中
音频输入（语音转文本）被包含在 transcription_span() 中
音频输出（文本转语音）被包含在 speech_span() 中
相关的音频跨度可以置于 speech_group_span() 下方

默认情况下，追踪命名为“Agent workflow”。如果您使用 trace，可以设置此名称，或者可以使用 RunConfig 配置名称和其他属性。

此外，您可以设置自定义追踪处理器，以将追踪推送到其他目的地（作为替代或辅助目的地）。

更高级别的追踪

有时，您可能希望多次调用 run() 属于单个追踪。您可以通过将整个代码包含在 trace() 中来做到这一点。

from agents import Agent, Runner, trace

async def main():
    agent = Agent(name="Joke generator", instructions="Tell funny jokes.")

    with trace("Joke workflow"): # (1)!
        first_result = await Runner.run(agent, "Tell me a joke")
        second_result = await Runner.run(agent, f"Rate this joke: {first_result.final_output}")
        print(f"Joke: {first_result.final_output}")
        print(f"Rating: {second_result.final_output}")

由于对 Runner.run 的两次调用都包含在 with trace() 中，因此单个运行将成为整个追踪的一部分，而不是创建两个追踪。

创建追踪

您可以使用 trace() 函数来创建追踪。追踪需要启动和完成。您有两种选择

推荐：使用追踪作为上下文管理器，即 with trace(...) as my_trace。这将自动在正确的时间启动和结束追踪。
您也可以手动调用 trace.start() 和 trace.finish()。

当前追踪通过 Python contextvar 跟踪。这意味着它可以自动处理并发。如果您手动启动/结束追踪，则需要将 mark_as_current 和 reset_current 传递给 start()/finish() 以更新当前追踪。

创建跨度

您可以使用各种 *_span() 方法来创建跨度。通常，您不需要手动创建跨度。提供了一个 custom_span() 函数来跟踪自定义跨度信息。

跨度自动属于当前追踪，并嵌套在最近的当前跨度下方，该跨度通过 Python contextvar 跟踪。

敏感数据

某些跨度可能会捕获潜在的敏感数据。

generation_span() 存储 LLM 生成的输入/输出，而 function_span() 存储函数调用的输入/输出。这些可能包含敏感数据，因此您可以禁用通过 RunConfig.trace_include_sensitive_data 捕获该数据。

同样，音频跨度默认包含输入和输出音频的 base64 编码 PCM 数据。您可以配置 VoicePipelineConfig.trace_include_sensitive_audio_data 以禁用捕获此音频数据。

自定义追踪处理器

追踪的高级架构是

在初始化时，我们创建一个全局 TraceProvider，它负责创建追踪。
我们使用 BatchTraceProcessor 配置 TraceProvider，该处理器以批处理方式将追踪/跨度发送到 BackendSpanExporter，后者以批处理方式将跨度和追踪导出到 OpenAI 后端。

要自定义此默认设置，以将追踪发送到替代或额外的后端或修改导出器行为，您有两种选择

add_trace_processor() 允许您添加一个额外的追踪处理器，该处理器将在追踪和跨度准备就绪时接收它们。这允许您进行自己的处理，除了将追踪发送到 OpenAI 后端之外。
set_trace_processors() 允许您使用自己的追踪处理器替换默认处理器。这意味着除非您包含执行此操作的 TracingProcessor，否则追踪将不会发送到 OpenAI 后端。

使用非 OpenAI 模型进行追踪

您可以使用 OpenAI API 密钥和非 OpenAI 模型，以便在 OpenAI 追踪仪表板中启用免费追踪，而无需禁用追踪。

import os
from agents import set_tracing_export_api_key, Agent, Runner
from agents.extensions.models.litellm_model import LitellmModel

tracing_api_key = os.environ["OPENAI_API_KEY"]
set_tracing_export_api_key(tracing_api_key)

model = LitellmModel(
    model="your-model-name",
    api_key="your-api-key",
)

agent = Agent(
    name="Assistant",
    model=model,
)

如果您只需要为单个运行使用不同的追踪密钥，请通过 RunConfig 传递它，而不是更改全局导出器。

from agents import Runner, RunConfig

await Runner.run(
    agent,
    input="Hello",
    run_config=RunConfig(tracing={"api_key": "sk-tracing-123"}),
)

注意事项

在 Openai 追踪仪表板上查看免费追踪。

追踪