追踪

Agents SDK包含内置的追踪功能，可以全面记录agent运行期间的事件：LLM生成、工具调用、交接、防护栏以及发生的自定义事件。通过Traces仪表盘，您可以在开发和产品环境中调试、可视化和监控工作流。

注意

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

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

追踪和跨度

Traces表示"工作流"的端到端操作，由Spans组成。Trace具有以下属性：
- workflow_name: 逻辑工作流或应用名称，如"代码生成"或"客户服务"
- trace_id: 追踪的唯一ID，不提供时会自动生成，格式必须为trace_<32位字母数字>
- group_id: 可选组ID，用于关联同一会话的多个追踪，如聊天线程ID
- disabled: 如果为True，则不会记录该追踪
- metadata: 可选的追踪元数据
Spans表示有开始和结束时间的操作，具有：
- started_at和ended_at时间戳
- trace_id表示所属的追踪
- parent_id指向该Span的父Span(如果有)
- span_data包含Span的信息，如AgentSpanData包含Agent信息，GenerationSpanData包含LLM生成信息等

默认追踪

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="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跟踪，这意味着它能自动处理并发。如果手动启动/结束追踪，需要向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，负责创建追踪
配置TraceProvider使用BatchTraceProcessor，将追踪/跨度批量发送到BackendSpanExporter，后者将跨度和追踪批量导出到OpenAI后端

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

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

追踪