追踪 (Tracing)

Agents SDK 内置了强大的追踪功能，它能全面记录代理运行过程中的各种事件：LLM 生成内容、工具调用、交接操作、防护措施，甚至是自定义事件。通过 Traces 仪表板，你可以在开发和生产环境中轻松调试、可视化和监控你的工作流。

注意

追踪功能默认是开启的。如果你想关闭它，有两种方法：

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

Traces 和 spans

• Traces 代表一个工作流的完整操作过程，由多个 Spans 组成。Traces 具有以下属性：
  • workflow_name：表示逻辑工作流或应用。比如"代码生成"或"客户服务"。
  • trace_id：每个 trace 的唯一标识符。如果你不提供，系统会自动生成。格式必须是 trace_<32位字母数字组合>。
  • group_id：可选的组 ID，用于链接同一对话中的多个 traces。例如，你可以使用聊天线程 ID。
  • disabled：如果为 True，则不会记录该 trace。
  • metadata：trace 的可选元数据。
• Spans 表示有开始和结束时间的操作。Spans 包含：
  • started_at 和 ended_at 时间戳。
  • trace_id，表示它所属的 trace
  • parent_id，指向该 Span 的父 Span（如果有的话）
  • span_data，包含关于该 Span 的信息。例如，AgentSpanData 包含代理信息，GenerationSpanData 包含 LLM 生成的信息，等等。

默认追踪

SDK 默认会追踪以下内容：

• 整个 Runner.{run, run_sync, run_streamed}() 会被 trace() 包装。
• 每次代理运行时，都会被 agent_span() 包装
• LLM 生成内容时会被 generation_span() 包装
• 函数工具调用分别被 function_span() 包装
• 防护措施被 guardrail_span() 包装
• 交接操作被 handoff_span() 包装

默认情况下，trace 的名称是 "Agent trace"。如果你使用 trace，可以设置这个名称，或者通过 RunConfig 配置名称和其他属性。

此外，你还可以设置自定义 trace 处理器，将 traces 推送到其他目标（作为替代或辅助目标）。

更高级别的 traces

有时，你可能希望多次调用 run() 成为单个 trace 的一部分。你可以通过将整个代码包装在 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_output.final_output}")
        print(f"笑话：{first_result.final_output}")
        print(f"评分：{second_result.final_output}")

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

创建 traces

你可以使用 trace() 函数创建一个 trace。Traces 需要被启动和结束。你有两种选择：

1. 推荐：将 trace 作为上下文管理器使用，即 with trace(...) as my_trace。这将在适当的时候自动启动和结束 trace。
2. 你也可以手动调用 trace.start() 和 trace.finish()。

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

创建 spans

你可以使用各种 *_span() 方法创建 span。通常，你不需要手动创建 spans。我们提供了 custom_span() 函数用于跟踪自定义 span 信息。

Spans 自动成为当前 trace 的一部分，并嵌套在最近的当前 span 下，这也是通过 Python contextvar 进行跟踪的。

敏感数据

某些 spans 会跟踪潜在的敏感数据。例如，generation_span() 存储 LLM 生成的输入/输出，而 function_span() 存储函数调用的输入/输出。这些可能包含敏感数据，因此你可以通过 RunConfig.trace_include_sensitive_data 禁用捕获这些数据。

自定义追踪处理器

追踪的高级架构如下：

• 在初始化时，我们创建一个全局 TraceProvider，负责创建 traces。
• 我们使用 BatchTraceProcessor 配置 TraceProvider，它将 traces/spans 批量发送到 BackendSpanExporter，后者将 spans 和 traces 批量导出到 OpenAI 后端。

要自定义这个默认设置，将 traces 发送到其他或额外的后端，或修改导出器行为，你有两个选择：

1. add_trace_processor() 让你添加额外的trace 处理器，它会在 traces 和 spans 准备好时接收它们。这样你可以在将 traces 发送到 OpenAI 后端的同时进行自己的处理。
2. set_trace_processors() 让你用自己的 trace 处理器替换默认处理器。这意味着除非你包含一个能发送到 OpenAI 后端的 TracingProcessor，否则 traces 不会被发送到 OpenAI 后端。

外部 trace 处理器包括：

• Braintrust
• Pydantic Logfire
• AgentOps