追踪

Agents SDK 包含内置的追踪功能，可在 agent 运行期间收集全面的事件记录：大语言模型生成、工具调用、交接/切换、安全护栏，甚至发生的自定义事件。使用追踪仪表板，你可以在开发和生产过程中调试、可视化和监控工作流程。

注意

追踪功能默认开启。有两种方法可以禁用追踪： 1. 你可以通过设置环境变量 OPENAI_AGENTS_DISABLE_TRACING=1 全局禁用追踪。 2. 你可以通过将 agents.run.RunConfig.tracing_disabled 设置为 True 来禁用单次运行的追踪。

对于遵循零数据保留 (ZDR) 策略使用 OpenAI API 的组织，无法使用追踪功能。

追踪和跨度

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

默认追踪

默认情况下，SDK 会追踪以下内容： - 整个 Runner.{run, run_sync, run_streamed}() 都被包装在 trace() 中。 - 每次运行 agent 时，它都被包装在 agent_span() 中。 - LLM 生成过程被包装在 generation_span() 中。 - 每个函数工具调用都被包装在 function_span() 中。 - 安全护栏被包装在 guardrail_span() 中。 - 交接/切换被包装在 handoff_span() 中。 - 音频输入（语音转文本）被包装在 transcription_span() 中。 - 音频输出（文本转语音）被包装在 speech_span() 中。 - 相关音频跨度可能作为 speech_group_span() 的子项。

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

此外，可以设置自定义追踪处理器，将追踪信息发送到其他目标（作为替代目标或辅助目标）。

更高级别的追踪

有时，可能希望多次调用 run() 成为单个追踪的一部分。可以通过将整个代码包装在 trace() 中来实现。

from agents import Agent, Runner, trace

async def main():
    agent = Agent(name="笑话生成器", instructions="讲有趣的笑话。")

    with trace("笑话工作流程"): # (1)!
        first_result = await Runner.run(agent, "给我讲个笑话")
        second_result = await Runner.run(agent, f"给这个笑话打分：{first_result.final_output}")
        print(f"笑话：{first_result.final_output}")
        print(f"评分：{second_result.final_output}")

1. 因为对 Runner.run 的两次调用都被包装在 with trace() 中，所以各个运行将成为整体追踪的一部分，而不是创建两个追踪。

创建追踪记录

你可以使用trace()函数来创建追踪记录。追踪记录需要启动和结束。你有两种方式来实现： 1. 推荐方式：将追踪记录用作上下文管理器，即with trace(...) as my_trace。这将在合适的时间自动启动和结束追踪记录。 2. 你也可以手动调用trace.start()和trace.finish()。

当前的追踪记录是通过Python的contextvar进行跟踪的。这意味着它可以自动处理并发情况。如果你手动启动/结束追踪记录，你需要在start()/finish()中传递mark_as_current和reset_current来更新当前的追踪记录。

创建跨度

你可以使用各种*_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后端。

若要自定义此默认设置，以便将追踪记录发送到其他后端或额外的后端，或者修改导出器行为，你有两种选择： 1. add_trace_processor() 允许你添加一个额外的追踪处理器，该处理器将在追踪记录和跨度准备好时接收它们。这使你除了将追踪记录发送到OpenAI后端之外，还能进行自己的处理。 2. set_trace_processors() 允许你用自己的追踪处理器替换默认处理器。这意味着除非你包含一个能将追踪记录发送到OpenAI后端的TracingProcessor，否则追踪记录不会被发送到OpenAI后端。

追踪