OpenAI Agents SDK 追踪Tracing完全指南内置 Span 体系、敏感数据处理与自定义导出【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本篇技术指南系统讲解 OpenAI Agents Python SDKopenai-agents-python内置的可观测性能力——Tracing。它记录了 Agent 运行全过程的 LLM 生成、工具调用、交接handoff、护栏guardrail与自定义事件帮助你基于 OpenAI Traces 仪表盘对工作流进行调试、可视化与线上监控。读完本文你将掌握默认追踪行为与三种禁用方式、Trace/Span 核心概念、如何在长运行 Worker 中保证立即导出、如何合并多次运行到同一 Trace、如何保护敏感数据以及如何通过自定义 Tracing Processor 将数据转发或替换到其他后端。概览内置追踪默认开启Agents SDK 内置了 Tracing 能力会在一次 Agent 运行期间收集完整的事件记录LLM 生成generation、工具调用tool call、交接handoff、护栏guardrail以及你自定义的任何事件。这些数据可以提交到 OpenAI Traces 仪表盘用于开发期与生产环境的调试、可视化和监控。追踪默认是开启的有三种常见方式可以全局或按运行关闭环境变量全局禁用设置OPENAI_AGENTS_DISABLE_TRACING1代码全局禁用调用set_tracing_disabled(True)其内部实现为get_trace_provider().set_disabled(disabled)单次运行禁用在Runner.run()时传入RunConfig.tracing_disabledTrue。注意根据 docs/tracing.md在 Zero Data RetentionZDR策略下使用 OpenAI API 的组织无法使用 Tracing。从源码结构看禁用并不会破坏代码逻辑当追踪被禁用时trace()会返回NoOpTrace见 traces.pyspan 创建会返回NoOpSpan见 spans.py。它们保留完整的上下文管理行为__enter__/__exit__但export()返回None不记录、不上传任何数据因此你的业务代码无需做任何分支处理。核心概念Trace 与 SpanTracing 的数据模型由两层结构组成Trace追踪Trace代表一个端到端的工作流操作由多个 Span 组成。一个 Trace 拥有以下属性属性说明workflow_name逻辑工作流或应用的名称例如 Code generation 或 Customer servicetrace_id该 Trace 的唯一 ID。不传则自动生成格式必须为trace_32位字母数字group_id可选分组 ID用于关联同一会话的多条 Trace例如聊天线程 IDdisabled若为True该 Trace 不会被记录metadata可选的附加元数据字典Span跨度Span代表一个有明确开始和结束时间的操作属性包括属性说明started_at/ended_at开始与结束的 ISO 时间戳trace_id所属 Trace 的 IDparent_id父 Span 的 ID如果有用于构建嵌套层级span_data该 Span 的操作信息例如AgentSpanData包含 Agent 信息GenerationSpanData包含 LLM 生成信息在实现层面TraceImpl在构造时若未提供trace_id会调用util.gen_trace_id()自动生成见 traces.pySpanImpl同理使用util.gen_span_id()生成 span ID见 spans.py。Span 导出的载荷结构为{object: trace.span, id, trace_id, parent_id, started_at, ended_at, span_data, error, metadata}见 spans.py。默认追踪行为Runner 自动生成的 Span 体系默认情况下SDK 会自动追踪以下内容无需任何配置追踪对象Span 类型整个Runner.{run, run_sync, run_streamed}()外层包裹一个trace()每次 Runner 调用task_span()每个模型轮次model turnturn_span()每个 Agent 的执行agent_span()每次 LLM 生成generation_span()每次函数工具调用function_span()护栏检查guardrail_span()Agent 交接handoff_span()音频输入语音转文字transcription_span()音频输出文字转语音speech_span()相关联的音频 Span可能被挂在speech_group_span()下默认的 Trace 名称是字面字符串Agent workflow。如果使用trace()创建 Trace 可以自定义名称如果使用Runner.run()自动创建的 Trace则可通过RunConfig配置名称与其他属性包括workflow_name运行名称默认Agent workflowtrace_id自定义 Trace IDgroup_id会话分组 IDtrace_metadata附加元数据字典。更紧凑的层级关闭 task/turn span如果希望层级更紧凑可以在单次运行中禁用自动的 task 与 turn span——此时agent_span、generation_span、function_span、guardrail_span、handoff_span以及自定义 span 仍然会被记录from agents import RunConfig, Runner result await Runner.run( agent, Hello, run_configRunConfig(tracing{include_task_and_turn_spans: False}), )这里的tracing参数对应TracingConfig它是一个 TypedDict目前支持两个可选键api_key导出该运行 Trace 时使用的 API Keyinclude_task_and_turn_spans是否创建 task/turn span省略时默认为True见 config.py。此外你还可以通过 自定义 Tracing Processor 将 Trace 推送到其他目标作为默认后端的替代或补充。长运行 Worker 与立即导出默认的BatchTraceProcessor会在后台每几秒批量导出一次 Trace或者当内存队列达到触发阈值时提前导出并在进程退出时执行最终 flush。这意味着在 Celery、RQ、Dramatiq 或 FastAPI 后台任务这类长运行 Worker 中Trace 通常无需额外代码即可自动导出但每个任务结束后的数据可能不会立刻出现在 Traces 仪表盘上。如果你需要在某个工作单元结束时获得立即交付保证请在 Trace 上下文退出后调用flush_traces()。Celery 任务示例from agents import Runner, flush_traces, trace celery_app.task def run_agent_task(prompt: str): try: with trace(celery_task): result Runner.run_sync(agent, prompt) return result.final_output finally: flush_traces()FastAPI 后台任务示例from fastapi import BackgroundTasks, FastAPI from agents import Runner, flush_traces, trace app FastAPI() def process_in_background(prompt: str) - None: try: with trace(background_job): Runner.run_sync(agent, prompt) finally: flush_traces() app.post(/run) async def run(prompt: str, background_tasks: BackgroundTasks): background_tasks.add_task(process_in_background, prompt) return {status: queued}调用时机很重要flush_traces()会阻塞直到当前缓冲的 Trace 和 Span 全部导出完成所以要放在trace()关闭之后调用避免 flush 一个尚未构建完整的 Trace。如果默认的导出延迟可以接受则可以跳过该调用。从源码看flush_traces()实际调用全局TraceProvider.force_flush()见init.py最终进入BatchTraceProcessor.force_flush()的_export_batches()一次性排空队列中的全部条目。BatchTraceProcessor的默认参数为max_queue_size8192、max_batch_size128、schedule_delay5.0秒、export_trigger_ratio0.7即队列达到 8192 × 0.7 ≈ 5734 条时提前触发导出并采用独立的后台守护线程消费队列避免阻塞 Agent 主执行路径见 processors.py。高层 Trace把多次运行合并为一条 Trace有时你希望多次run()调用归属于同一条 Trace。将整段代码包在with trace()中即可实现from agents import Agent, Runner, trace async def main(): agent Agent(nameJoke generator, instructionsTell funny jokes.) with trace(Joke workflow): # (1)! first_result await Runner.run(agent, Tell me a joke) second_result await Runner.run(agent, fRate this joke: {first_result.final_output}) print(fJoke: {first_result.final_output}) print(fRating: {second_result.final_output})因为两次Runner.run被包在with trace()中两次运行都会成为同一条总 Trace 的一部分而不是各自创建独立 Trace。这一机制的底层支撑是 Python 的contextvars当前 Trace 通过contextvar追踪因此天然支持并发多个异步任务可以各自维护自己的当前 Trace/当前 Span。TraceImpl.start()在mark_as_currentTrue时通过Scope.set_current_trace(self)写入当前上下文见 traces.py。手动创建 Trace 与 Span创建 Trace使用trace()函数创建 Trace。Trace 需要显式开始与结束有两种方式推荐方式作为上下文管理器使用即with trace(...) as my_traceSDK 会在正确时机自动开始与结束手动方式调用trace.start()与trace.finish()。trace()的完整签名参数参数类型说明workflow_namestr逻辑应用或工作流名称例如code_bot、customer_support_agenttrace_idstr \| NoneTrace ID推荐用gen_trace_id()生成以保证格式正确group_idstr \| None可选分组标识用于关联同一会话/进程的多条 Trace例如聊天线程 IDmetadatadict \| None附加到 Trace 的任意元数据字典tracingTracingConfig \| None该 Trace 的导出配置disabledbool若为True返回 Trace 但不会被记录如果你手动 start/finish请向start()传入mark_as_current、向finish()传入reset_current以更新当前 Trace上下文。另外从源码可以看出若当前上下文已存在 Trace 时再次创建新 Tracetrace()会打印警告日志Trace already exists...见 create.py提示这很可能是错误用法。创建 Span一般情况下无需手动创建 Span——Runner 会自动创建上面表格中的各类 Span。但你也可以使用各种*_span()工厂函数按需创建全部定义在 create.py函数核心参数用途agent_span(name, handoffs, tools, output_type)Agent 名称、可交接 Agent 列表、可用工具列表、输出类型记录 Agent 执行task_span(name)名称记录一次顶层 Runner 调用turn_span(turn, agent_name)轮次号、Agent 名称记录一次 Agent 循环轮次function_span(name, input, output)函数名、输入、输出记录工具/函数调用generation_span(input, output, model, model_config, usage)消息序列、模型与配置、用量记录一次 LLM 生成response_span(response)OpenAI Response 对象仅记录模型响应 ID 等轻量信息handoff_span(from_agent, to_agent)来源/目标 Agent 名记录 Agent 交接guardrail_span(name, triggered)名称、是否触发记录护栏检查transcription_span(model, input, output, ...)语音转文字模型与 PCM 音频记录音频输入speech_span(model, input, output, ...)文字转语音模型与 PCM 音频记录音频输出speech_group_span(input)输入文本组合相关联的音频 Spanmcp_tools_span(server, result)MCP 服务器名与结果记录 MCP 工具列表调用custom_span(name, data)名称与任意结构化数据记录自定义事件每个*_span()都支持span_id、parent未传则自动挂到当前 Trace/Span 下与disabled参数。custom_span()是记录自定义业务信息的主要入口且支持通过set_error()标记错误from agents import custom_span with custom_span(database_query, {operation: SELECT, table: users}) as span: results await db.query(SELECT * FROM users) span.span_data.data[output] {count: len(results)}Span 会自动归属于当前 Trace并嵌套在最近的当前 Span 之下——这也是通过 Pythoncontextvar追踪实现的。SpanImpl的__enter__会执行start(mark_as_currentTrue)__exit__会执行finish(reset_currentTrue)确保层级关系正确闭合见 spans.py。敏感数据处理部分 Span 可能捕获潜在的敏感数据需要特别关注generation_span()会存储 LLM 生成的输入/输出function_span()会存储函数调用的输入/输出音频类 Span默认包含输入/输出音频的base64 编码 PCM 数据。你可以通过以下方式控制RunConfig.trace_include_sensitive_data控制是否在 Trace 中捕获 generation/function span 的输入输出数据。默认值为True见 run_config.py且可通过环境变量OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA设置默认值取true/1也接受yes/on或false/0。注意即使设为FalseSDK 仍会为这些事件创建 Span只是不包含敏感数据本身VoicePipelineConfig.trace_include_sensitive_audio_data控制是否捕获音频 PCM 数据。从源码实现可以验证该开关的作用范围例如在 mcp/util.py 中只有在context.run_config为None或trace_include_sensitive_data为真时才会把工具输出写回当前 FunctionSpan 的span_data.output在openai_responses.py、openai_chatcompletions.py、any_llm_model.py、litellm_model.py等多个模型适配器中trace_include_sensitive_datatracing.include_data()也被用于控制生成错误时是否记录完整数据。环境变量默认值解析逻辑见 run_config.py。自定义 Tracing 处理器默认架构Tracing 的高层架构如下初始化时SDK 创建一个全局TraceProvider负责创建 Trace首次访问时惰性初始化见 setup.py因此导入 SDK 不会立即创建网络客户端或线程该TraceProvider配置了一个BatchTraceProcessor按批把 Trace/Span 发送给BackendSpanExporter后者批量导出到 OpenAI 后端。BackendSpanExporter的导出细节见 processors.py使用 HTTP 客户端保持连接池请求头携带Authorization: Bearer api_key、OpenAI-Beta: tracesv1并可选携带OpenAI-Organization/OpenAI-Project默认端点即 OpenAI traces ingest 服务失败时采用指数退避 抖动重试默认max_retries3、base_delay1.0s、max_delay30.0s4xx 客户端错误不重试5xx/网络错误重试字段超过 100KB 时会被截断字符串追加... [truncated]后缀复杂结构生成{truncated: true, original_type: ..., preview: ...}预览未设置 API Key 时会告警并跳过导出。两种自定义方式1.add_trace_processor()—— 追加处理器在默认发送到 OpenAI 后端的基础上额外注册一个处理器它会在 Trace/Span 就绪时收到同样的数据适合做自己的二次处理日志、指标、转发等。2.set_trace_processors()—— 替换处理器用自定义处理器替换默认处理器列表。这意味着除非你包含一个真正上传到 OpenAI 的TracingProcessor否则 Trace 不会发往 OpenAI 后端。自定义处理器需要实现TracingProcessor抽象接口的六个方法方法触发时机说明on_trace_start(trace)Trace 开始应快速返回避免阻塞执行on_trace_end(trace)Trace 完成适合导出/处理完整 Traceon_span_start(span)Span 开始同步回调需线程安全on_span_end(span)Span 完成适合导出单个 Spanshutdown()应用停止清理资源、flush 队列force_flush()强制 flush处理完所有排队条目后返回from agents.tracing import TracingProcessor class CustomProcessor(TracingProcessor): def __init__(self): self.active_traces {} self.active_spans {} def on_trace_start(self, trace): self.active_traces[trace.trace_id] trace def on_trace_end(self, trace): del self.active_traces[trace.trace_id] def on_span_start(self, span): self.active_spans[span.span_id] span def on_span_end(self, span): del self.active_spans[span.span_id] def shutdown(self): self.active_traces.clear() self.active_spans.clear() def force_flush(self): pass注册方式from agents import add_trace_processor add_trace_processor(CustomProcessor())此外processors.py 还内置了一个ConsoleSpanExporter可以把 Trace/Span 打印到控制台受_debug.DONT_LOG_MODEL_DATA/DONT_LOG_TOOL_DATA开关控制开启时数据会被脱敏为[Exporter] ... data is redacted.非常适合本地调试。SDK 还在进程退出时通过atexit注册了全局 shutdown超时默认 5 秒见 setup.py保证退出前完成最后导出。使用非 OpenAI 模型时的追踪当使用非 OpenAI 模型时你可以为 tracing exporter 提供一个 OpenAI API Key从而无需关闭追踪即可在 OpenAI Traces 仪表盘免费查看 Trace。第三方模型适配器的选择与设置注意事项参见 Models 指南中的 Third-party adapters 一节。import os from agents import set_tracing_export_api_key, Agent from agents.extensions.models.any_llm_model import AnyLLMModel tracing_api_key os.environ[OPENAI_API_KEY] set_tracing_export_api_key(tracing_api_key) model AnyLLMModel( modelyour-provider/your-model-name, api_keyyour-api-key, ) agent Agent( nameAssistant, modelmodel, )set_tracing_export_api_key()的实现是调用default_exporter().set_api_key(api_key)见init.py即修改全局默认 exporter 的 API Key。如果你只想为单次运行使用不同的追踪 Key则不必修改全局 exporter直接通过RunConfig传入即可from agents import Runner, RunConfig await Runner.run( agent, inputHello, run_configRunConfig(tracing{api_key: sk-tracing-123}), )从BackendSpanExporter._export_with_deadline的实现可以确认见 processors.py导出时会按tracing_api_key对条目分组每条 Trace/Span 上携带的独立 Key 优先于全局 Key 使用——这正是RunConfig.tracing.api_key能按运行覆盖的原因。其他注意事项可以在 OpenAI Traces 仪表盘查看免费 Trace长运行进程如 Worker 常驻任务请结合上文flush_traces()的时机建议在需要即时可见的场景主动导出。生态集成Tracing API 得到了大量社区与厂商集成的支持覆盖外部可观测性/追踪平台相关集成方包括Weights BiasesWeave、Arize Phoenix、Future AGI、MLflow自托管/OSS 与 Databricks 托管、Braintrust、Pydantic Logfire、AgentOps、Scorecard、Respan、LangSmith、Maxim AI、Comet Opik、Langfuse、Langtrace、Okahu-Monocle、Galileo、Portkey AI、LangDB AI、Agenta、PostHog、Traccia、PromptLayer、HoneyHive、Asqav、Datadog、Latitude、DProvenanceKit、Tuning Engines 等。这些集成的接入方式与各自平台的配置要求请查阅对应厂商文档完整的集成列表以官方文档见 docs/tracing.md 的 Ecosystem integrations 一节为准。参考实现路径速查以下为本文涉及的关键源码与文档位置便于进一步深入阅读追踪公共 APIadd_trace_processor、set_trace_processors、set_tracing_disabled、set_tracing_export_api_key、flush_tracessrc/agents/tracing/init.py各类 Span 工厂函数与trace()src/agents/tracing/create.pyTrace 实现含NoOpTrace、持久化TraceStatesrc/agents/tracing/traces.pySpan 实现含NoOpSpan、SpanErrorsrc/agents/tracing/spans.py批量导出、后端导出器与重试/截断逻辑src/agents/tracing/processors.py处理器与导出器抽象接口src/agents/tracing/processor_interface.pyTracingConfigapi_key、include_task_and_turn_spanssrc/agents/tracing/config.py全局 Provider 的惰性初始化与 shutdownsrc/agents/tracing/setup.pyRunConfig的追踪相关字段tracing_disabled、tracing、trace_include_sensitive_data、workflow_name、trace_id、group_id、trace_metadatasrc/agents/run_config.py官方追踪文档原文docs/tracing.md第三方模型适配器与追踪说明docs/models/index.md【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenAI Agents SDK 追踪Tracing完全指南内置 Span 体系、敏感数据处理与自定义导出【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本篇技术指南系统讲解 OpenAI Agents Python SDKopenai-agents-python内置的可观测性能力——Tracing。它记录了 Agent 运行全过程的 LLM 生成、工具调用、交接handoff、护栏guardrail与自定义事件帮助你基于 OpenAI Traces 仪表盘对工作流进行调试、可视化与线上监控。读完本文你将掌握默认追踪行为与三种禁用方式、Trace/Span 核心概念、如何在长运行 Worker 中保证立即导出、如何合并多次运行到同一 Trace、如何保护敏感数据以及如何通过自定义 Tracing Processor 将数据转发或替换到其他后端。概览内置追踪默认开启Agents SDK 内置了 Tracing 能力会在一次 Agent 运行期间收集完整的事件记录LLM 生成generation、工具调用tool call、交接handoff、护栏guardrail以及你自定义的任何事件。这些数据可以提交到 OpenAI Traces 仪表盘用于开发期与生产环境的调试、可视化和监控。追踪默认是开启的有三种常见方式可以全局或按运行关闭环境变量全局禁用设置OPENAI_AGENTS_DISABLE_TRACING1代码全局禁用调用set_tracing_disabled(True)其内部实现为get_trace_provider().set_disabled(disabled)单次运行禁用在Runner.run()时传入RunConfig.tracing_disabledTrue。注意根据 docs/tracing.md在 Zero Data RetentionZDR策略下使用 OpenAI API 的组织无法使用 Tracing。从源码结构看禁用并不会破坏代码逻辑当追踪被禁用时trace()会返回NoOpTrace见 traces.pyspan 创建会返回NoOpSpan见 spans.py。它们保留完整的上下文管理行为__enter__/__exit__但export()返回None不记录、不上传任何数据因此你的业务代码无需做任何分支处理。核心概念Trace 与 SpanTracing 的数据模型由两层结构组成Trace追踪Trace代表一个端到端的工作流操作由多个 Span 组成。一个 Trace 拥有以下属性属性说明workflow_name逻辑工作流或应用的名称例如 Code generation 或 Customer servicetrace_id该 Trace 的唯一 ID。不传则自动生成格式必须为trace_32位字母数字group_id可选分组 ID用于关联同一会话的多条 Trace例如聊天线程 IDdisabled若为True该 Trace 不会被记录metadata可选的附加元数据字典Span跨度Span代表一个有明确开始和结束时间的操作属性包括属性说明started_at/ended_at开始与结束的 ISO 时间戳trace_id所属 Trace 的 IDparent_id父 Span 的 ID如果有用于构建嵌套层级span_data该 Span 的操作信息例如AgentSpanData包含 Agent 信息GenerationSpanData包含 LLM 生成信息在实现层面TraceImpl在构造时若未提供trace_id会调用util.gen_trace_id()自动生成见 traces.pySpanImpl同理使用util.gen_span_id()生成 span ID见 spans.py。Span 导出的载荷结构为{object: trace.span, id, trace_id, parent_id, started_at, ended_at, span_data, error, metadata}见 spans.py。默认追踪行为Runner 自动生成的 Span 体系默认情况下SDK 会自动追踪以下内容无需任何配置追踪对象Span 类型整个Runner.{run, run_sync, run_streamed}()外层包裹一个trace()每次 Runner 调用task_span()每个模型轮次model turnturn_span()每个 Agent 的执行agent_span()每次 LLM 生成generation_span()每次函数工具调用function_span()护栏检查guardrail_span()Agent 交接handoff_span()音频输入语音转文字transcription_span()音频输出文字转语音speech_span()相关联的音频 Span可能被挂在speech_group_span()下默认的 Trace 名称是字面字符串Agent workflow。如果使用trace()创建 Trace 可以自定义名称如果使用Runner.run()自动创建的 Trace则可通过RunConfig配置名称与其他属性包括workflow_name运行名称默认Agent workflowtrace_id自定义 Trace IDgroup_id会话分组 IDtrace_metadata附加元数据字典。更紧凑的层级关闭 task/turn span如果希望层级更紧凑可以在单次运行中禁用自动的 task 与 turn span——此时agent_span、generation_span、function_span、guardrail_span、handoff_span以及自定义 span 仍然会被记录from agents import RunConfig, Runner result await Runner.run( agent, Hello, run_configRunConfig(tracing{include_task_and_turn_spans: False}), )这里的tracing参数对应TracingConfig它是一个 TypedDict目前支持两个可选键api_key导出该运行 Trace 时使用的 API Keyinclude_task_and_turn_spans是否创建 task/turn span省略时默认为True见 config.py。此外你还可以通过 自定义 Tracing Processor 将 Trace 推送到其他目标作为默认后端的替代或补充。长运行 Worker 与立即导出默认的BatchTraceProcessor会在后台每几秒批量导出一次 Trace或者当内存队列达到触发阈值时提前导出并在进程退出时执行最终 flush。这意味着在 Celery、RQ、Dramatiq 或 FastAPI 后台任务这类长运行 Worker 中Trace 通常无需额外代码即可自动导出但每个任务结束后的数据可能不会立刻出现在 Traces 仪表盘上。如果你需要在某个工作单元结束时获得立即交付保证请在 Trace 上下文退出后调用flush_traces()。Celery 任务示例from agents import Runner, flush_traces, trace celery_app.task def run_agent_task(prompt: str): try: with trace(celery_task): result Runner.run_sync(agent, prompt) return result.final_output finally: flush_traces()FastAPI 后台任务示例from fastapi import BackgroundTasks, FastAPI from agents import Runner, flush_traces, trace app FastAPI() def process_in_background(prompt: str) - None: try: with trace(background_job): Runner.run_sync(agent, prompt) finally: flush_traces() app.post(/run) async def run(prompt: str, background_tasks: BackgroundTasks): background_tasks.add_task(process_in_background, prompt) return {status: queued}调用时机很重要flush_traces()会阻塞直到当前缓冲的 Trace 和 Span 全部导出完成所以要放在trace()关闭之后调用避免 flush 一个尚未构建完整的 Trace。如果默认的导出延迟可以接受则可以跳过该调用。从源码看flush_traces()实际调用全局TraceProvider.force_flush()见init.py最终进入BatchTraceProcessor.force_flush()的_export_batches()一次性排空队列中的全部条目。BatchTraceProcessor的默认参数为max_queue_size8192、max_batch_size128、schedule_delay5.0秒、export_trigger_ratio0.7即队列达到 8192 × 0.7 ≈ 5734 条时提前触发导出并采用独立的后台守护线程消费队列避免阻塞 Agent 主执行路径见 processors.py。高层 Trace把多次运行合并为一条 Trace有时你希望多次run()调用归属于同一条 Trace。将整段代码包在with trace()中即可实现from agents import Agent, Runner, trace async def main(): agent Agent(nameJoke generator, instructionsTell funny jokes.) with trace(Joke workflow): # (1)! first_result await Runner.run(agent, Tell me a joke) second_result await Runner.run(agent, fRate this joke: {first_result.final_output}) print(fJoke: {first_result.final_output}) print(fRating: {second_result.final_output})因为两次Runner.run被包在with trace()中两次运行都会成为同一条总 Trace 的一部分而不是各自创建独立 Trace。这一机制的底层支撑是 Python 的contextvars当前 Trace 通过contextvar追踪因此天然支持并发多个异步任务可以各自维护自己的当前 Trace/当前 Span。TraceImpl.start()在mark_as_currentTrue时通过Scope.set_current_trace(self)写入当前上下文见 traces.py。手动创建 Trace 与 Span创建 Trace使用trace()函数创建 Trace。Trace 需要显式开始与结束有两种方式推荐方式作为上下文管理器使用即with trace(...) as my_traceSDK 会在正确时机自动开始与结束手动方式调用trace.start()与trace.finish()。trace()的完整签名参数参数类型说明workflow_namestr逻辑应用或工作流名称例如code_bot、customer_support_agenttrace_idstr \| NoneTrace ID推荐用gen_trace_id()生成以保证格式正确group_idstr \| None可选分组标识用于关联同一会话/进程的多条 Trace例如聊天线程 IDmetadatadict \| None附加到 Trace 的任意元数据字典tracingTracingConfig \| None该 Trace 的导出配置disabledbool若为True返回 Trace 但不会被记录如果你手动 start/finish请向start()传入mark_as_current、向finish()传入reset_current以更新当前 Trace上下文。另外从源码可以看出若当前上下文已存在 Trace 时再次创建新 Tracetrace()会打印警告日志Trace already exists...见 create.py提示这很可能是错误用法。创建 Span一般情况下无需手动创建 Span——Runner 会自动创建上面表格中的各类 Span。但你也可以使用各种*_span()工厂函数按需创建全部定义在 create.py函数核心参数用途agent_span(name, handoffs, tools, output_type)Agent 名称、可交接 Agent 列表、可用工具列表、输出类型记录 Agent 执行task_span(name)名称记录一次顶层 Runner 调用turn_span(turn, agent_name)轮次号、Agent 名称记录一次 Agent 循环轮次function_span(name, input, output)函数名、输入、输出记录工具/函数调用generation_span(input, output, model, model_config, usage)消息序列、模型与配置、用量记录一次 LLM 生成response_span(response)OpenAI Response 对象仅记录模型响应 ID 等轻量信息handoff_span(from_agent, to_agent)来源/目标 Agent 名记录 Agent 交接guardrail_span(name, triggered)名称、是否触发记录护栏检查transcription_span(model, input, output, ...)语音转文字模型与 PCM 音频记录音频输入speech_span(model, input, output, ...)文字转语音模型与 PCM 音频记录音频输出speech_group_span(input)输入文本组合相关联的音频 Spanmcp_tools_span(server, result)MCP 服务器名与结果记录 MCP 工具列表调用custom_span(name, data)名称与任意结构化数据记录自定义事件每个*_span()都支持span_id、parent未传则自动挂到当前 Trace/Span 下与disabled参数。custom_span()是记录自定义业务信息的主要入口且支持通过set_error()标记错误from agents import custom_span with custom_span(database_query, {operation: SELECT, table: users}) as span: results await db.query(SELECT * FROM users) span.span_data.data[output] {count: len(results)}Span 会自动归属于当前 Trace并嵌套在最近的当前 Span 之下——这也是通过 Pythoncontextvar追踪实现的。SpanImpl的__enter__会执行start(mark_as_currentTrue)__exit__会执行finish(reset_currentTrue)确保层级关系正确闭合见 spans.py。敏感数据处理部分 Span 可能捕获潜在的敏感数据需要特别关注generation_span()会存储 LLM 生成的输入/输出function_span()会存储函数调用的输入/输出音频类 Span默认包含输入/输出音频的base64 编码 PCM 数据。你可以通过以下方式控制RunConfig.trace_include_sensitive_data控制是否在 Trace 中捕获 generation/function span 的输入输出数据。默认值为True见 run_config.py且可通过环境变量OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA设置默认值取true/1也接受yes/on或false/0。注意即使设为FalseSDK 仍会为这些事件创建 Span只是不包含敏感数据本身VoicePipelineConfig.trace_include_sensitive_audio_data控制是否捕获音频 PCM 数据。从源码实现可以验证该开关的作用范围例如在 mcp/util.py 中只有在context.run_config为None或trace_include_sensitive_data为真时才会把工具输出写回当前 FunctionSpan 的span_data.output在openai_responses.py、openai_chatcompletions.py、any_llm_model.py、litellm_model.py等多个模型适配器中trace_include_sensitive_datatracing.include_data()也被用于控制生成错误时是否记录完整数据。环境变量默认值解析逻辑见 run_config.py。自定义 Tracing 处理器默认架构Tracing 的高层架构如下初始化时SDK 创建一个全局TraceProvider负责创建 Trace首次访问时惰性初始化见 setup.py因此导入 SDK 不会立即创建网络客户端或线程该TraceProvider配置了一个BatchTraceProcessor按批把 Trace/Span 发送给BackendSpanExporter后者批量导出到 OpenAI 后端。BackendSpanExporter的导出细节见 processors.py使用 HTTP 客户端保持连接池请求头携带Authorization: Bearer api_key、OpenAI-Beta: tracesv1并可选携带OpenAI-Organization/OpenAI-Project默认端点即 OpenAI traces ingest 服务失败时采用指数退避 抖动重试默认max_retries3、base_delay1.0s、max_delay30.0s4xx 客户端错误不重试5xx/网络错误重试字段超过 100KB 时会被截断字符串追加... [truncated]后缀复杂结构生成{truncated: true, original_type: ..., preview: ...}预览未设置 API Key 时会告警并跳过导出。两种自定义方式1.add_trace_processor()—— 追加处理器在默认发送到 OpenAI 后端的基础上额外注册一个处理器它会在 Trace/Span 就绪时收到同样的数据适合做自己的二次处理日志、指标、转发等。2.set_trace_processors()—— 替换处理器用自定义处理器替换默认处理器列表。这意味着除非你包含一个真正上传到 OpenAI 的TracingProcessor否则 Trace 不会发往 OpenAI 后端。自定义处理器需要实现TracingProcessor抽象接口的六个方法方法触发时机说明on_trace_start(trace)Trace 开始应快速返回避免阻塞执行on_trace_end(trace)Trace 完成适合导出/处理完整 Traceon_span_start(span)Span 开始同步回调需线程安全on_span_end(span)Span 完成适合导出单个 Spanshutdown()应用停止清理资源、flush 队列force_flush()强制 flush处理完所有排队条目后返回from agents.tracing import TracingProcessor class CustomProcessor(TracingProcessor): def __init__(self): self.active_traces {} self.active_spans {} def on_trace_start(self, trace): self.active_traces[trace.trace_id] trace def on_trace_end(self, trace): del self.active_traces[trace.trace_id] def on_span_start(self, span): self.active_spans[span.span_id] span def on_span_end(self, span): del self.active_spans[span.span_id] def shutdown(self): self.active_traces.clear() self.active_spans.clear() def force_flush(self): pass注册方式from agents import add_trace_processor add_trace_processor(CustomProcessor())此外processors.py 还内置了一个ConsoleSpanExporter可以把 Trace/Span 打印到控制台受_debug.DONT_LOG_MODEL_DATA/DONT_LOG_TOOL_DATA开关控制开启时数据会被脱敏为[Exporter] ... data is redacted.非常适合本地调试。SDK 还在进程退出时通过atexit注册了全局 shutdown超时默认 5 秒见 setup.py保证退出前完成最后导出。使用非 OpenAI 模型时的追踪当使用非 OpenAI 模型时你可以为 tracing exporter 提供一个 OpenAI API Key从而无需关闭追踪即可在 OpenAI Traces 仪表盘免费查看 Trace。第三方模型适配器的选择与设置注意事项参见 Models 指南中的 Third-party adapters 一节。import os from agents import set_tracing_export_api_key, Agent from agents.extensions.models.any_llm_model import AnyLLMModel tracing_api_key os.environ[OPENAI_API_KEY] set_tracing_export_api_key(tracing_api_key) model AnyLLMModel( modelyour-provider/your-model-name, api_keyyour-api-key, ) agent Agent( nameAssistant, modelmodel, )set_tracing_export_api_key()的实现是调用default_exporter().set_api_key(api_key)见init.py即修改全局默认 exporter 的 API Key。如果你只想为单次运行使用不同的追踪 Key则不必修改全局 exporter直接通过RunConfig传入即可from agents import Runner, RunConfig await Runner.run( agent, inputHello, run_configRunConfig(tracing{api_key: sk-tracing-123}), )从BackendSpanExporter._export_with_deadline的实现可以确认见 processors.py导出时会按tracing_api_key对条目分组每条 Trace/Span 上携带的独立 Key 优先于全局 Key 使用——这正是RunConfig.tracing.api_key能按运行覆盖的原因。其他注意事项可以在 OpenAI Traces 仪表盘查看免费 Trace长运行进程如 Worker 常驻任务请结合上文flush_traces()的时机建议在需要即时可见的场景主动导出。生态集成Tracing API 得到了大量社区与厂商集成的支持覆盖外部可观测性/追踪平台相关集成方包括Weights BiasesWeave、Arize Phoenix、Future AGI、MLflow自托管/OSS 与 Databricks 托管、Braintrust、Pydantic Logfire、AgentOps、Scorecard、Respan、LangSmith、Maxim AI、Comet Opik、Langfuse、Langtrace、Okahu-Monocle、Galileo、Portkey AI、LangDB AI、Agenta、PostHog、Traccia、PromptLayer、HoneyHive、Asqav、Datadog、Latitude、DProvenanceKit、Tuning Engines 等。这些集成的接入方式与各自平台的配置要求请查阅对应厂商文档完整的集成列表以官方文档见 docs/tracing.md 的 Ecosystem integrations 一节为准。参考实现路径速查以下为本文涉及的关键源码与文档位置便于进一步深入阅读追踪公共 APIadd_trace_processor、set_trace_processors、set_tracing_disabled、set_tracing_export_api_key、flush_tracessrc/agents/tracing/init.py各类 Span 工厂函数与trace()src/agents/tracing/create.pyTrace 实现含NoOpTrace、持久化TraceStatesrc/agents/tracing/traces.pySpan 实现含NoOpSpan、SpanErrorsrc/agents/tracing/spans.py批量导出、后端导出器与重试/截断逻辑src/agents/tracing/processors.py处理器与导出器抽象接口src/agents/tracing/processor_interface.pyTracingConfigapi_key、include_task_and_turn_spanssrc/agents/tracing/config.py全局 Provider 的惰性初始化与 shutdownsrc/agents/tracing/setup.pyRunConfig的追踪相关字段tracing_disabled、tracing、trace_include_sensitive_data、workflow_name、trace_id、group_id、trace_metadatasrc/agents/run_config.py官方追踪文档原文docs/tracing.md第三方模型适配器与追踪说明docs/models/index.md【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
