openai-agents-python Realtime Tracing 架构解析双轨追踪体系与客户端/服务端 Trace 关联实践【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python导读本文基于 openai-agents-python 仓库中 .agents/references/realtime-tracing.md 这一内部权威参考文档系统梳理 Realtime实时语音集成的追踪Tracing架构。Realtime 场景存在两条彼此独立的追踪路径Realtime API 服务端创建的会话追踪以及 Agents SDK 客户端通过trace()等工厂方法创建的本地追踪。本文会深入讲解RealtimeModelTracingConfig的完整配置面、默认行为、底层发送机制与可复现的验证方式帮助你在实际项目中正确区分、配置并关联这两类 Trace避免客户端有 Trace 就认为服务端活动已被捕获的常见误判。读完本文你将掌握 Realtime 双轨追踪的边界、group_id关联的正确用法以及 SDK 当前实现的能力边界。一、Realtime Tracing 的双轨体系两条独立的追踪路径Realtime 集成的可观测性天然分裂为两条互不隶属的路径。参考文档 .agents/references/realtime-tracing.md 用一个清晰的对照表概括了二者的归属、配置入口与产出路径归属方配置入口结果Realtime API 服务端追踪Realtime API服务端auto、workflow_name、group_id、metadata服务端在 Traces Dashboard 中创建一个 Realtime 会话 TraceAgents SDK 客户端追踪Agents SDK 追踪提供器tracing providertrace()、agent_span()及其他 SDK span 工厂方法SDK 通过其 tracing processor 导出本地创建的 Trace 与 Span理解这张表是使用 Realtime 追踪的前提任何一条路径的开启与否、内容是否完整都与另一条路径没有必然关系。1.1 两条路径的职责边界服务端路径负责捕获 Realtime 模型活动本身——会话创建、音频输入输出、响应生成、工具调用等发生在 Realtime API 服务端的事件最终呈现在 Traces Dashboard 上。客户端路径负责捕获 SDK 进程内的活动——例如你显式包裹的trace()/agent_span()所描述的业务流程与 SDK 本地操作。参考文档特别强调了一个关键事实.agents/references/realtime-tracing.md当前 Python SDK 不存在将 Agents SDK 客户端的trace_id、span_id或父上下文parent context映射进RealtimeModelTracingConfig或模型的session.update的机制。这意味着两条路径在当前实现下不会自动合并服务端创建的 Realtime Trace不会被挂接为某个 SDK 创建的 Trace/Span 的子节点在RealtimeSession外层包一个 SDK 的agent_span()也不会让服务端 Trace 的内容成为该 span 的子内容。如果两条路径同时开启Dashboard 上可能出现两条互不相干的 Trace。此时共用一个group_id只能让它们在过滤与关联时更容易配对并不能把二者合并也不会建立父子关系。1.2 为什么会出现双 Trace而不是统一层级参考文档给出原因SDK 客户端 Trace 的父级上下文parent context无法穿过 Realtime 追踪配置传递到服务端。从源码结构看RealtimeModelTracingConfig定义于 src/agents/realtime/config.py只承载workflow_name、group_id、metadata三个字段其中并不包含任何trace_id/span_id或 parent span 信息详见下文第二节因此服务端没有可用的父级信息来把 Realtime 会话 Trace 挂到客户端层级之下。这与Runner的运行模型形成鲜明对比——Runner会创建统一的 Trace 层级根 Trace 下挂 agent span、工具 span 等而 Realtime 当前无法复刻这一统一层级。二、RealtimeModelTracingConfig三个字段与完整类型面服务端追踪的配置入口是RealtimeModelTracingConfig它在 src/agents/realtime/config.py 中以TypedDict定义class RealtimeModelTracingConfig(TypedDict): Configuration for tracing in realtime model sessions. workflow_name: NotRequired[str] The workflow name to use for tracing. group_id: NotRequired[str] A group identifier to use for tracing, to link multiple traces together. metadata: NotRequired[dict[str, Any]] Additional metadata to include with the trace.三个字段的语义如下字段类型必填作用workflow_namestr否该 Trace 的工作流名称用于在 Dashboard 上标识这条 Realtime 会话 Tracegroup_idstr否分组标识符用于把多条 Trace 关联link到一起便于过滤与对照metadatadict[str, Any]否附加元数据随 Trace 一同提交该配置通过RealtimeSessionModelSettings.tracing字段挂到会话级设置上见 src/agents/realtime/config.py 中RealtimeSessionModelSettings的tracing: NotRequired[RealtimeModelTracingConfig | None]最终由RealtimeRunner/RealtimeSession在建立会话时下发。需要注意tracing取值既可以是RealtimeModelTracingConfig字典也可以是字符串auto还可以是None显式关闭服务端追踪。2.1 与 SDK 客户端 trace() 的参数对照作为对照SDK 客户端的trace()工厂方法见 src/agents/tracing/create.py同样接收workflow_name、group_id、metadata但额外支持trace_id、tracing等参数def trace( workflow_name: str, trace_id: str | None None, group_id: str | None None, metadata: dict[str, Any] | None None, tracing: TracingConfig | None None, ... )二者字段同名但分属不同系统trace()创建的是客户端 Trace 对象本地RealtimeModelTracingConfig则是要随session.update发给 Realtime API 服务端的服务端 Trace 描述。trace_id/父级上下文这类信息只有客户端系统才有且不会流入RealtimeModelTracingConfig——这正是双轨无法自动建立父子关系的原因。三、默认行为未配置时自动启用服务端追踪参考文档总结了当前 Python SDK 的四个关键行为.agents/references/realtime-tracing.md下面逐一对照源码验证RealtimeModelTracingConfig仅暴露workflow_name、group_id、metadata已在上文确认src/agents/realtime/config.py。OpenAIRealtimeWebSocketModel在调用方未提供配置时默认将追踪配置设为auto见 src/agents/realtime/openai_realtime.pyif tracing in model_settings: self._tracing_config model_settings[tracing] else: self._tracing_config auto也就是说只要你不显式传入tracing服务端追踪默认开启auto交由 Realtime API 自行决定如何命名/组织 Trace。收到session.created后模型通过session.update事件下发追踪配置见 src/agents/realtime/openai_realtime.py 的事件分发逻辑elif parsed.type session.created: await self._send_tracing_config(self._tracing_config)以及_send_tracing_config的实现async def _send_tracing_config( self, tracing_config: RealtimeModelTracingConfig | Literal[auto] | None ) - None: Update tracing configuration via session.update event. if tracing_config is not None: converted_tracing_config _ConversionHelper.convert_tracing_config(tracing_config) await self._send_raw_message( OpenAISessionUpdateEvent( sessionOpenAISessionCreateRequest( modelself.model, typerealtime, tracingconverted_tracing_config, ), typesession.update, ) )可见追踪配置不是建立连接时就发送而是等服务端先回session.created之后再以session.update事件补发。这与 Realtime API 的会话协商时序一致。RealtimeRunConfig.tracing_disabled可阻止 SDK 为该会话开启 Realtime 追踪两处实现相互印证。在 src/agents/realtime/openai_realtime.py 的_build_model_settings_from_agent中if run_config and run_config.get(tracing_disabled, False): updated_settings[tracing] None在 src/agents/realtime/session.py 的_get_updated_model_settings_from_agent中也有等价逻辑disable_tracing self._run_config.get(tracing_disabled, False) if disable_tracing: updated_settings[tracing] None当tracing被置为None后_send_tracing_config(None)直接跳过发送if tracing_config is not None分支不成立即服务端收不到任何追踪配置也就不会为该会话创建服务端 Trace。3.1 配置转换链路_ConversionHelper.convert_tracing_configsrc/agents/realtime/openai_realtime.py负责把 SDK 侧的RealtimeModelTracingConfig字典转换为 OpenAI 官方客户端库的OpenAITracingConfigurationclassmethod def convert_tracing_config( cls, tracing_config: RealtimeModelTracingConfig | Literal[auto] | None ) - OpenAITracingConfiguration | Literal[auto] | None: if tracing_config is None: return None elif tracing_config auto: return auto return OpenAITracingConfiguration( group_idtracing_config.get(group_id), metadatatracing_config.get(metadata), workflow_nametracing_config.get(workflow_name), )转换规则一目了然None → None不发送追踪配置、auto → auto原样透传、字典 → 逐字段映射为官方类型。相关单元测试覆盖了全部三种形态见 tests/realtime/test_conversion_helpers.py 的TestConversionHelperTracingConfigNone、auto、完整字典、部分字典、空字典五种用例以及 tests/realtime/test_openai_realtime_conversions.py 的test_convert_tracing_config_variants。四、实操配置示例如何开启、定制与关闭服务端追踪结合 docs/realtime/guide.md 给出的 Realtime 配置骨架与本文第二节的类型面一个完整的配置示例放在RealtimeRunner(config...)的model_settings中如下from agents.realtime.config import RealtimeModelTracingConfig runner RealtimeRunner( starting_agentagent, config{ model_settings: { model_name: gpt-realtime-2.1, audio: { input: { format: pcm16, transcription: {model: gpt-4o-mini-transcribe}, turn_detection: {type: semantic_vad, interrupt_response: True}, }, output: {format: pcm16, voice: ash}, }, tool_choice: auto, # 服务端追踪配置三条路径默认 auto / 显式字典 / 显式关闭 tracing: { workflow_name: realtime-support-agent, group_id: support-session-20260909-001, metadata: {env: production, region: ap-east-1}, }, } }, )配置要点不写tracing字段等价于auto服务端追踪默认开启见第三节行为 2传tracing: {...}字典服务端按workflow_name命名 Tracegroup_id用于跨 Trace 关联metadata附加自定义信息传tracing: None或开启tracing_disabled不发送追踪配置服务端不创建该会话的 Realtime Trace。4.1 通过 RealtimeRunConfig.tracing_disabled 关闭除了在model_settings.tracing传None还可以在运行级配置中统一关闭。RealtimeRunConfig定义于 src/agents/realtime/config.py其中class RealtimeRunConfig(TypedDict): Configuration for running a realtime agent session. model_settings: NotRequired[RealtimeSessionModelSettings] Settings for the realtime model session. output_guardrails: NotRequired[list[OutputGuardrail[Any]]] List of output guardrails to run on the agents responses. guardrails_settings: NotRequired[RealtimeGuardrailsSettings] Settings for guardrail execution. tracing_disabled: NotRequired[bool] Whether tracing is disabled for this run. async_tool_calls: NotRequired[bool] Whether function tool calls should run asynchronously. Defaults to True. tool_execution: NotRequired[RealtimeToolExecutionConfig] SDK-side execution settings for local realtime tool calls. tool_error_formatter: NotRequired[ToolErrorFormatter] Optional callback that formats tool error messages returned to the model.tracing_disabledTrue时会话构建阶段src/agents/realtime/session.py会把model_settings[tracing]强制置为None与model_settings.tracingNone殊途同归。该运行级开关适合在按环境如测试/灰度统一关闭服务端追踪时使用。runner RealtimeRunner( starting_agentagent, config{ model_settings: {model_name: gpt-realtime-2.1}, tracing_disabled: True, # 本次运行不开启 Realtime 服务端追踪 }, )4.2 发送时序验证服务端追踪配置的实际发送时序是WebSocket 连接建立 → 服务端下发session.created→ 客户端调用_send_tracing_config发送session.update携带tracing。如果之后又通过update_agent或 handoff 切换 agent会话设置会通过RealtimeModelSendSessionUpdate再次下发见 src/agents/realtime/session.py 的update_agent与 handoff 处理路径其中同样包含_get_updated_model_settings_from_agent对tracing_disabled的处理保证切换后仍遵守运行级开关。五、双轨关联的正确姿势group_id 与 metadata由于当前实现无法让服务端 Trace 成为客户端 Trace/Span 的子节点参考文档给出的建议是.agents/references/realtime-tracing.md用服务端 Trace 承载 Realtime 模型活动当需要与客户端 Trace 关联时使用共享的group_id或 metadata。实践中推荐的做法职责划分Realtime 模型活动会话、音频、响应一律看服务端 Trace客户端进程内的业务流程一律看 SDK 客户端 Trace。关联手段为同一次业务请求生成一个共享标识如会话 ID 或请求 ID同时写入客户端trace(group_id...)与model_settings.tracing.group_id让两条 Trace 在 Dashboard 上可被过滤和配对from agents.tracing import trace shared_group_id fsupport-session-{session_id} # 客户端 Trace描述 SDK 进程内流程 with trace( workflow_namerealtime-support, group_idshared_group_id, metadata{session_id: session_id}, ): # 服务端 Trace通过 RealtimeModelTracingConfig 携带同一个 group_id runner RealtimeRunner( starting_agentagent, config{ model_settings: { model_name: gpt-realtime-2.1, tracing: { workflow_name: realtime-support, group_id: shared_group_id, metadata: {session_id: session_id}, }, } }, ) session await runner.run() # ... 会话交互预期管理共享group_id只解决找得到、对得上不解决连成树。Dashboard 上依然是两条独立 Trace需要人工或按group_id过滤对照查看。六、维护者约束评审与实现的五条铁律参考文档以维护者约束Maintainer Constraints的形式给出了评审/实现 Realtime 追踪行为时必须遵守的五条规则这也是读者判断某段代码行为是否符合设计意图的检查清单先判定归属某个行为到底属于 Realtime API 的服务端 Trace还是用trace()创建的 Agents SDK 客户端 Trace——两条路径互不替代。客户端 span 不能补救服务端在客户端加一个agent_span()不会修复缺失的服务端追踪也不会产生Runner那种统一 Trace 层级。父级传递缺口是当前实现限制当前 Python SDK 无法把服务端 Realtime span 挂到 SDK 创建的 Trace/Span 之下因为客户端 Trace 父级不会进入 Realtime 追踪配置。参考文档同时提醒在把这一缺口当作永久性限制之前应通过$openai-knowledge复核线上协议——即这是当前实现的能力边界而非协议层面的终局结论。正确分工Realtime 模型活动用服务端 Trace需要与客户端 Trace 关联时用共享group_id或 metadata。并行 SDK span 需要显式契约若要在 SDK 侧并行创建 span覆盖双 Trace 用户体验、异步任务上下文、handoff 父子关系、失败清理、以及仅存在于客户端的操作必须配套明确的产品与维护契约否则会产生语义混乱的 span 树。非空不等于已捕获一条客户端 Trace 变得非空不能证明 Realtime 服务端活动已被捕获或已正确挂父级——这是最容易踩的坑务必区分客户端有数据与服务端活动已入 Trace。七、从源码验证本篇文章的结论以下是本文全部关键结论对应的仓库证据位置便于你自行复核结论证据位置RealtimeModelTracingConfig仅含三字段src/agents/realtime/config.pyRealtimeModelTracingConfig定义默认autosrc/agents/realtime/openai_realtime.py_setup中if tracing in model_settings分支session.created后经session.update下发src/agents/realtime/openai_realtime.py_send_tracing_config与事件分发tracing_disabled置空 tracingsrc/agents/realtime/openai_realtime.py 与 src/agents/realtime/session.py 两处实现转换链路三态映射src/agents/realtime/openai_realtime.pyconvert_tracing_config转换行为测试覆盖tests/realtime/test_conversion_helpers.py 与 tests/realtime/test_openai_realtime_conversions.py客户端trace()/agent_span()参数src/agents/tracing/create.py运行级/会话级配置完整类型面src/agents/realtime/config.pyRealtimeRunConfig、RealtimeSessionModelSettings提示参考文档 .agents/references/realtime-tracing.md 特别提醒——Realtime 追踪支持随时间演进过多次验证行为时应以上述源码路径为准不要依赖旧 issue 描述在修改协议相关行为前用$openai-knowledge复核官方 API 参考。总结openai-agents-python 的 Realtime 追踪由两条独立路径构成Realtime API 服务端 Trace 与 Agents SDK 客户端 Trace。前者通过RealtimeModelTracingConfigworkflow_name/group_id/metadata配置默认auto开启在session.created后随session.update下发并可用tracing: None或RealtimeRunConfig.tracing_disabled关闭后者由trace()/agent_span()创建并在本地导出。当前实现不把客户端父级上下文传入服务端配置因此两条 Trace 无法自动合并为Runner那样的统一层级——需要用共享group_id或 metadata 进行关联并在评审与排障时始终区分客户端 Trace 非空与服务端活动已被捕获这两个事实。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 6:15:01 · 阅读 1.2k openai-agents-python Realtime Tracing 架构解析：双轨追踪体系与客户端/服务端 Trace 关联实践
openai-agents-python Realtime Tracing 架构解析双轨追踪体系与客户端/服务端 Trace 关联实践【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python导读本文基于 openai-agents-python 仓库中 .agents/references/realtime-tracing.md 这一内部权威参考文档系统梳理 Realtime实时语音集成的追踪Tracing架构。Realtime 场景存在两条彼此独立的追踪路径Realtime API 服务端创建的会话追踪以及 Agents SDK 客户端通过trace()等工厂方法创建的本地追踪。本文会深入讲解RealtimeModelTracingConfig的完整配置面、默认行为、底层发送机制与可复现的验证方式帮助你在实际项目中正确区分、配置并关联这两类 Trace避免客户端有 Trace 就认为服务端活动已被捕获的常见误判。读完本文你将掌握 Realtime 双轨追踪的边界、group_id关联的正确用法以及 SDK 当前实现的能力边界。一、Realtime Tracing 的双轨体系两条独立的追踪路径Realtime 集成的可观测性天然分裂为两条互不隶属的路径。参考文档 .agents/references/realtime-tracing.md 用一个清晰的对照表概括了二者的归属、配置入口与产出路径归属方配置入口结果Realtime API 服务端追踪Realtime API服务端auto、workflow_name、group_id、metadata服务端在 Traces Dashboard 中创建一个 Realtime 会话 TraceAgents SDK 客户端追踪Agents SDK 追踪提供器tracing providertrace()、agent_span()及其他 SDK span 工厂方法SDK 通过其 tracing processor 导出本地创建的 Trace 与 Span理解这张表是使用 Realtime 追踪的前提任何一条路径的开启与否、内容是否完整都与另一条路径没有必然关系。1.1 两条路径的职责边界服务端路径负责捕获 Realtime 模型活动本身——会话创建、音频输入输出、响应生成、工具调用等发生在 Realtime API 服务端的事件最终呈现在 Traces Dashboard 上。客户端路径负责捕获 SDK 进程内的活动——例如你显式包裹的trace()/agent_span()所描述的业务流程与 SDK 本地操作。参考文档特别强调了一个关键事实.agents/references/realtime-tracing.md当前 Python SDK 不存在将 Agents SDK 客户端的trace_id、span_id或父上下文parent context映射进RealtimeModelTracingConfig或模型的session.update的机制。这意味着两条路径在当前实现下不会自动合并服务端创建的 Realtime Trace不会被挂接为某个 SDK 创建的 Trace/Span 的子节点在RealtimeSession外层包一个 SDK 的agent_span()也不会让服务端 Trace 的内容成为该 span 的子内容。如果两条路径同时开启Dashboard 上可能出现两条互不相干的 Trace。此时共用一个group_id只能让它们在过滤与关联时更容易配对并不能把二者合并也不会建立父子关系。1.2 为什么会出现双 Trace而不是统一层级参考文档给出原因SDK 客户端 Trace 的父级上下文parent context无法穿过 Realtime 追踪配置传递到服务端。从源码结构看RealtimeModelTracingConfig定义于 src/agents/realtime/config.py只承载workflow_name、group_id、metadata三个字段其中并不包含任何trace_id/span_id或 parent span 信息详见下文第二节因此服务端没有可用的父级信息来把 Realtime 会话 Trace 挂到客户端层级之下。这与Runner的运行模型形成鲜明对比——Runner会创建统一的 Trace 层级根 Trace 下挂 agent span、工具 span 等而 Realtime 当前无法复刻这一统一层级。二、RealtimeModelTracingConfig三个字段与完整类型面服务端追踪的配置入口是RealtimeModelTracingConfig它在 src/agents/realtime/config.py 中以TypedDict定义class RealtimeModelTracingConfig(TypedDict): Configuration for tracing in realtime model sessions. workflow_name: NotRequired[str] The workflow name to use for tracing. group_id: NotRequired[str] A group identifier to use for tracing, to link multiple traces together. metadata: NotRequired[dict[str, Any]] Additional metadata to include with the trace.三个字段的语义如下字段类型必填作用workflow_namestr否该 Trace 的工作流名称用于在 Dashboard 上标识这条 Realtime 会话 Tracegroup_idstr否分组标识符用于把多条 Trace 关联link到一起便于过滤与对照metadatadict[str, Any]否附加元数据随 Trace 一同提交该配置通过RealtimeSessionModelSettings.tracing字段挂到会话级设置上见 src/agents/realtime/config.py 中RealtimeSessionModelSettings的tracing: NotRequired[RealtimeModelTracingConfig | None]最终由RealtimeRunner/RealtimeSession在建立会话时下发。需要注意tracing取值既可以是RealtimeModelTracingConfig字典也可以是字符串auto还可以是None显式关闭服务端追踪。2.1 与 SDK 客户端 trace() 的参数对照作为对照SDK 客户端的trace()工厂方法见 src/agents/tracing/create.py同样接收workflow_name、group_id、metadata但额外支持trace_id、tracing等参数def trace( workflow_name: str, trace_id: str | None None, group_id: str | None None, metadata: dict[str, Any] | None None, tracing: TracingConfig | None None, ... )二者字段同名但分属不同系统trace()创建的是客户端 Trace 对象本地RealtimeModelTracingConfig则是要随session.update发给 Realtime API 服务端的服务端 Trace 描述。trace_id/父级上下文这类信息只有客户端系统才有且不会流入RealtimeModelTracingConfig——这正是双轨无法自动建立父子关系的原因。三、默认行为未配置时自动启用服务端追踪参考文档总结了当前 Python SDK 的四个关键行为.agents/references/realtime-tracing.md下面逐一对照源码验证RealtimeModelTracingConfig仅暴露workflow_name、group_id、metadata已在上文确认src/agents/realtime/config.py。OpenAIRealtimeWebSocketModel在调用方未提供配置时默认将追踪配置设为auto见 src/agents/realtime/openai_realtime.pyif tracing in model_settings: self._tracing_config model_settings[tracing] else: self._tracing_config auto也就是说只要你不显式传入tracing服务端追踪默认开启auto交由 Realtime API 自行决定如何命名/组织 Trace。收到session.created后模型通过session.update事件下发追踪配置见 src/agents/realtime/openai_realtime.py 的事件分发逻辑elif parsed.type session.created: await self._send_tracing_config(self._tracing_config)以及_send_tracing_config的实现async def _send_tracing_config( self, tracing_config: RealtimeModelTracingConfig | Literal[auto] | None ) - None: Update tracing configuration via session.update event. if tracing_config is not None: converted_tracing_config _ConversionHelper.convert_tracing_config(tracing_config) await self._send_raw_message( OpenAISessionUpdateEvent( sessionOpenAISessionCreateRequest( modelself.model, typerealtime, tracingconverted_tracing_config, ), typesession.update, ) )可见追踪配置不是建立连接时就发送而是等服务端先回session.created之后再以session.update事件补发。这与 Realtime API 的会话协商时序一致。RealtimeRunConfig.tracing_disabled可阻止 SDK 为该会话开启 Realtime 追踪两处实现相互印证。在 src/agents/realtime/openai_realtime.py 的_build_model_settings_from_agent中if run_config and run_config.get(tracing_disabled, False): updated_settings[tracing] None在 src/agents/realtime/session.py 的_get_updated_model_settings_from_agent中也有等价逻辑disable_tracing self._run_config.get(tracing_disabled, False) if disable_tracing: updated_settings[tracing] None当tracing被置为None后_send_tracing_config(None)直接跳过发送if tracing_config is not None分支不成立即服务端收不到任何追踪配置也就不会为该会话创建服务端 Trace。3.1 配置转换链路_ConversionHelper.convert_tracing_configsrc/agents/realtime/openai_realtime.py负责把 SDK 侧的RealtimeModelTracingConfig字典转换为 OpenAI 官方客户端库的OpenAITracingConfigurationclassmethod def convert_tracing_config( cls, tracing_config: RealtimeModelTracingConfig | Literal[auto] | None ) - OpenAITracingConfiguration | Literal[auto] | None: if tracing_config is None: return None elif tracing_config auto: return auto return OpenAITracingConfiguration( group_idtracing_config.get(group_id), metadatatracing_config.get(metadata), workflow_nametracing_config.get(workflow_name), )转换规则一目了然None → None不发送追踪配置、auto → auto原样透传、字典 → 逐字段映射为官方类型。相关单元测试覆盖了全部三种形态见 tests/realtime/test_conversion_helpers.py 的TestConversionHelperTracingConfigNone、auto、完整字典、部分字典、空字典五种用例以及 tests/realtime/test_openai_realtime_conversions.py 的test_convert_tracing_config_variants。四、实操配置示例如何开启、定制与关闭服务端追踪结合 docs/realtime/guide.md 给出的 Realtime 配置骨架与本文第二节的类型面一个完整的配置示例放在RealtimeRunner(config...)的model_settings中如下from agents.realtime.config import RealtimeModelTracingConfig runner RealtimeRunner( starting_agentagent, config{ model_settings: { model_name: gpt-realtime-2.1, audio: { input: { format: pcm16, transcription: {model: gpt-4o-mini-transcribe}, turn_detection: {type: semantic_vad, interrupt_response: True}, }, output: {format: pcm16, voice: ash}, }, tool_choice: auto, # 服务端追踪配置三条路径默认 auto / 显式字典 / 显式关闭 tracing: { workflow_name: realtime-support-agent, group_id: support-session-20260909-001, metadata: {env: production, region: ap-east-1}, }, } }, )配置要点不写tracing字段等价于auto服务端追踪默认开启见第三节行为 2传tracing: {...}字典服务端按workflow_name命名 Tracegroup_id用于跨 Trace 关联metadata附加自定义信息传tracing: None或开启tracing_disabled不发送追踪配置服务端不创建该会话的 Realtime Trace。4.1 通过 RealtimeRunConfig.tracing_disabled 关闭除了在model_settings.tracing传None还可以在运行级配置中统一关闭。RealtimeRunConfig定义于 src/agents/realtime/config.py其中class RealtimeRunConfig(TypedDict): Configuration for running a realtime agent session. model_settings: NotRequired[RealtimeSessionModelSettings] Settings for the realtime model session. output_guardrails: NotRequired[list[OutputGuardrail[Any]]] List of output guardrails to run on the agents responses. guardrails_settings: NotRequired[RealtimeGuardrailsSettings] Settings for guardrail execution. tracing_disabled: NotRequired[bool] Whether tracing is disabled for this run. async_tool_calls: NotRequired[bool] Whether function tool calls should run asynchronously. Defaults to True. tool_execution: NotRequired[RealtimeToolExecutionConfig] SDK-side execution settings for local realtime tool calls. tool_error_formatter: NotRequired[ToolErrorFormatter] Optional callback that formats tool error messages returned to the model.tracing_disabledTrue时会话构建阶段src/agents/realtime/session.py会把model_settings[tracing]强制置为None与model_settings.tracingNone殊途同归。该运行级开关适合在按环境如测试/灰度统一关闭服务端追踪时使用。runner RealtimeRunner( starting_agentagent, config{ model_settings: {model_name: gpt-realtime-2.1}, tracing_disabled: True, # 本次运行不开启 Realtime 服务端追踪 }, )4.2 发送时序验证服务端追踪配置的实际发送时序是WebSocket 连接建立 → 服务端下发session.created→ 客户端调用_send_tracing_config发送session.update携带tracing。如果之后又通过update_agent或 handoff 切换 agent会话设置会通过RealtimeModelSendSessionUpdate再次下发见 src/agents/realtime/session.py 的update_agent与 handoff 处理路径其中同样包含_get_updated_model_settings_from_agent对tracing_disabled的处理保证切换后仍遵守运行级开关。五、双轨关联的正确姿势group_id 与 metadata由于当前实现无法让服务端 Trace 成为客户端 Trace/Span 的子节点参考文档给出的建议是.agents/references/realtime-tracing.md用服务端 Trace 承载 Realtime 模型活动当需要与客户端 Trace 关联时使用共享的group_id或 metadata。实践中推荐的做法职责划分Realtime 模型活动会话、音频、响应一律看服务端 Trace客户端进程内的业务流程一律看 SDK 客户端 Trace。关联手段为同一次业务请求生成一个共享标识如会话 ID 或请求 ID同时写入客户端trace(group_id...)与model_settings.tracing.group_id让两条 Trace 在 Dashboard 上可被过滤和配对from agents.tracing import trace shared_group_id fsupport-session-{session_id} # 客户端 Trace描述 SDK 进程内流程 with trace( workflow_namerealtime-support, group_idshared_group_id, metadata{session_id: session_id}, ): # 服务端 Trace通过 RealtimeModelTracingConfig 携带同一个 group_id runner RealtimeRunner( starting_agentagent, config{ model_settings: { model_name: gpt-realtime-2.1, tracing: { workflow_name: realtime-support, group_id: shared_group_id, metadata: {session_id: session_id}, }, } }, ) session await runner.run() # ... 会话交互预期管理共享group_id只解决找得到、对得上不解决连成树。Dashboard 上依然是两条独立 Trace需要人工或按group_id过滤对照查看。六、维护者约束评审与实现的五条铁律参考文档以维护者约束Maintainer Constraints的形式给出了评审/实现 Realtime 追踪行为时必须遵守的五条规则这也是读者判断某段代码行为是否符合设计意图的检查清单先判定归属某个行为到底属于 Realtime API 的服务端 Trace还是用trace()创建的 Agents SDK 客户端 Trace——两条路径互不替代。客户端 span 不能补救服务端在客户端加一个agent_span()不会修复缺失的服务端追踪也不会产生Runner那种统一 Trace 层级。父级传递缺口是当前实现限制当前 Python SDK 无法把服务端 Realtime span 挂到 SDK 创建的 Trace/Span 之下因为客户端 Trace 父级不会进入 Realtime 追踪配置。参考文档同时提醒在把这一缺口当作永久性限制之前应通过$openai-knowledge复核线上协议——即这是当前实现的能力边界而非协议层面的终局结论。正确分工Realtime 模型活动用服务端 Trace需要与客户端 Trace 关联时用共享group_id或 metadata。并行 SDK span 需要显式契约若要在 SDK 侧并行创建 span覆盖双 Trace 用户体验、异步任务上下文、handoff 父子关系、失败清理、以及仅存在于客户端的操作必须配套明确的产品与维护契约否则会产生语义混乱的 span 树。非空不等于已捕获一条客户端 Trace 变得非空不能证明 Realtime 服务端活动已被捕获或已正确挂父级——这是最容易踩的坑务必区分客户端有数据与服务端活动已入 Trace。七、从源码验证本篇文章的结论以下是本文全部关键结论对应的仓库证据位置便于你自行复核结论证据位置RealtimeModelTracingConfig仅含三字段src/agents/realtime/config.pyRealtimeModelTracingConfig定义默认autosrc/agents/realtime/openai_realtime.py_setup中if tracing in model_settings分支session.created后经session.update下发src/agents/realtime/openai_realtime.py_send_tracing_config与事件分发tracing_disabled置空 tracingsrc/agents/realtime/openai_realtime.py 与 src/agents/realtime/session.py 两处实现转换链路三态映射src/agents/realtime/openai_realtime.pyconvert_tracing_config转换行为测试覆盖tests/realtime/test_conversion_helpers.py 与 tests/realtime/test_openai_realtime_conversions.py客户端trace()/agent_span()参数src/agents/tracing/create.py运行级/会话级配置完整类型面src/agents/realtime/config.pyRealtimeRunConfig、RealtimeSessionModelSettings提示参考文档 .agents/references/realtime-tracing.md 特别提醒——Realtime 追踪支持随时间演进过多次验证行为时应以上述源码路径为准不要依赖旧 issue 描述在修改协议相关行为前用$openai-knowledge复核官方 API 参考。总结openai-agents-python 的 Realtime 追踪由两条独立路径构成Realtime API 服务端 Trace 与 Agents SDK 客户端 Trace。前者通过RealtimeModelTracingConfigworkflow_name/group_id/metadata配置默认auto开启在session.created后随session.update下发并可用tracing: None或RealtimeRunConfig.tracing_disabled关闭后者由trace()/agent_span()创建并在本地导出。当前实现不把客户端父级上下文传入服务端配置因此两条 Trace 无法自动合并为Runner那样的统一层级——需要用共享group_id或 metadata 进行关联并在评审与排障时始终区分客户端 Trace 非空与服务端活动已被捕获这两个事实。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考