企业官网建设流程全解析

openai-agents-python 语音流水线追踪指南：用 VoicePipelineConfig 配置语音 Agent 的 Trace 与敏感数据控制

【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python

本篇指南围绕 openai-agents-python（OpenAI Agents SDK）的语音流水线（Voice Pipeline）追踪机制展开：语音流水线与常规 Agent 一样会被自动追踪，同时可以通过VoicePipelineConfig精细控制追踪是否启用、是否记录语音转写等敏感数据、工作流名称、trace 分组与附加元数据。读完后，你能够独立配置一条语音链路的完整追踪策略，并结合源码理解tracing_disabled、trace_include_sensitive_data、trace_include_sensitive_audio_data、workflow_name、group_id、trace_metadata各字段在流水线执行中的真实生效位置。

语音流水线为什么默认就被追踪

Agents SDK 内置追踪（tracing）机制，会完整记录一次运行中的各类事件：LLM 生成、工具调用、handoff、guardrails 以及自定义事件，并可结合 OpenAI 的 Traces 仪表盘进行调试、可视化与生产监控（详见 通用追踪文档）。语音流水线遵循同样的默认行为：你不需要为VoicePipeline编写任何额外的埋点代码，追踪是自动完成的。

从源码结构看，这一"自动追踪"发生在 src/agents/voice/pipeline.py 中：

• 单轮输入（AudioInput）走_run_single_turn，整个异步处理生命周期被TraceCtxManager包住；
• 多轮流式输入（StreamedAudioInput）走_run_multi_turn，整个流式会话同样被TraceCtxManager包住（src/agents/voice/pipeline.py）。

两处构建 trace 上下文的参数完全一致：

# src/agents/voice/pipeline.py（简化自源码） with TraceCtxManager( workflow_name=self.config.workflow_name or "Voice Agent", trace_id=None, # 自动生成 group_id=self.config.group_id, metadata=self.config.trace_metadata, tracing=self.config.tracing, disabled=self.config.tracing_disabled, ): ...

也就是说，VoicePipelineConfig中的追踪相关字段，最终都逐一线性地映射到了 trace 上下文的创建参数上。在更底层，SDK 还会自动为音频相关操作创建专用 span：音频输入（语音转文字）被transcription_span()包裹、音频输出（文字转语音）被speech_span()包裹，SDK 还可能把相关音频 span 组织到speech_group_span()之下（见 src/agents/tracing/create.py 中三个 span 工厂函数的定义）。这些 span 默认会携带 base64 编码的 PCM 音频与转写文本，这正是下面几个敏感数据开关存在的意义。

此外需要注意通用追踪文档中提到的限制：对采用 OpenAI 零数据保留（Zero Data Retention，ZDR）策略的组织，追踪不可用；追踪默认开启，可通过环境变量OPENAI_AGENTS_DISABLE_TRACING=1、全局的set_tracing_disabled(True)、或单次运行的RunConfig.tracing_disabled关闭（见 docs/tracing.md）。

VoicePipelineConfig 的追踪字段全解

在通用追踪能力之上，语音流水线允许通过 [VoicePipelineConfig][agents.voice.pipeline_config.VoicePipelineConfig]（定义于 src/agents/voice/pipeline_config.py）单独配置一条管线的追踪行为。与追踪直接相关的关键字段如下：

以上默认值均可在 src/agents/voice/pipeline_config.py 的 dataclass 字段定义中逐一对应确认。

除文档明确列出的这六个字段外，从源码结构看，VoicePipelineConfig还额外提供tracing: TracingConfig | None字段（src/agents/voice/pipeline_config.py）。TracingConfig是一个TypedDict，目前支持api_key（用于导出 trace 的独立 API key，例如非 OpenAI 模型场景下单独指定追踪密钥）与include_task_and_turn_spans（见 src/agents/tracing/config.py）。在pipeline.py中它被原样传入TraceCtxManager的tracing参数，可用于为这条语音管线指定独立的追踪导出密钥，而无需改动全局导出器。

workflow_name 与 group_id：让语音 trace 可读、可关联

• workflow_name：语音场景下的 trace 名称默认为字面量"Voice Agent"（pipeline.py中还有self.config.workflow_name or "Voice Agent"的兜底逻辑）。如果你的服务同时运行多种语音 Agent，建议为每条管线设置不同的workflow_name，例如"Support phone line"，便于在仪表盘按工作流区分。
• group_id：默认值是field(default_factory=gen_group_id)，即每次构造VoicePipelineConfig时生成一个随机分组 ID（src/agents/voice/pipeline_config.py）。对于"一通电话/一个语音会话"这种业务概念，你可以在创建配置时显式传入业务侧的会话 ID（如通话记录 ID），这样该会话内产生的多条 trace 都能在仪表盘中按group_id聚合查看。
• trace_metadata：任意dict[str, Any]，适合携带渠道、区域、实验分组等排查上下文，随 trace 一并上报。

敏感数据的两级开关

这是语音追踪中最需要理解的一组设计：

• trace_include_sensitive_data：控制转写文本等敏感内容是否进入 trace。文档特别强调它的边界——"This is specifically for the voice pipeline, and not for anything that goes on inside your Workflow"，即它只管语音管线自身的 span（如 STT 转写 span），Workflow 内部 Agent 的 generation/function span 的敏感数据仍由RunConfig.trace_include_sensitive_data控制。
• trace_include_sensitive_audio_data：控制音频数据（base64 PCM）是否进入 trace。transcription_span的输入音频与speech_span的输出音频默认都会携带 PCM 音频数据（见 docs/tracing.md 的 Sensitive data 一节）。

从源码看这两个开关的落地路径非常直接：pipeline.py在调用 STT 时把两个布尔值一起传给模型层（src/agents/voice/pipeline.py、L160-L165），OpenAI STT 实现据此决定是否写入转写文本与音频（例如 src/agents/voice/models/openai_stt.py 中把两个开关保存为实例字段，并在创建 span 时条件性填充input/output）。TTS 侧同理，StreamedAudioResult在处理音频事件时也会检查这两个开关（src/agents/voice/result.py）。测试套件中有针对该行为的用例，例如 tests/voice/test_pipeline.py 中的test_segment_audio_is_retained_only_for_audio_tracing，验证音频片段仅当开启音频追踪时才会被保留。

实践中建议：

• 生产环境若合规要求不记录语音原文，可将两个开关都置为False，trace 仍然保留时间线、模型名等结构信息，但不再包含转写文本与 PCM 音频；
• 调试"转写为什么错了"这类问题时，保留trace_include_sensitive_data=True且关闭音频数据上报，通常是信息量与合规的折中。

另外，通用层的环境变量OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA（取值true/1或false/0）可以整体调整trace_include_sensitive_data的默认行为（见 docs/tracing.md），无需改代码即可切换部署环境的策略。

实战：为语音管线配置追踪

下面的示例展示如何构造一条带完整追踪配置的语音流水线。VoicePipeline的config参数接受VoicePipelineConfig实例或等价的 dict（dict 会被coerce_dataclass_config强制转换为 dataclass，见 src/agents/voice/pipeline.py）：

from agents import Agent, VoicePipeline from agents.voice.pipeline_config import VoicePipelineConfig agent = Agent( name="Support agent", instructions="You are a helpful phone support agent. Answer concisely.", ) config = VoicePipelineConfig( # 追踪总开关：False 表示启用追踪（默认值） tracing_disabled=False, # 记录转写文本等敏感数据（仅影响语音管线自身，不影响 Workflow 内部） trace_include_sensitive_data=True, # 记录 base64 PCM 音频数据 trace_include_sensitive_audio_data=False, # trace 在仪表盘中显示的工作流名称 workflow_name="Phone support line", # 用业务侧的会话 ID 关联同一通电话产生的多条 trace group_id="call-2026-0909-0001", # 附加自定义元数据，方便按渠道、实验分组排查 trace_metadata={"channel": "twilio", "locale": "en-US"}, ) pipeline = VoicePipeline( workflow=agent, # Agent 可直接作为 workflow 使用 config=config, )

要点回顾：

1. 不传config时，VoicePipeline会使用全默认的VoicePipelineConfig()，即"追踪开启 + 敏感数据全记录"；
2. tracing_disabled=True是该条管线级别的关闭方式，与全局OPENAI_AGENTS_DISABLE_TRACING、set_tracing_disabled(True)、RunConfig.tracing_disabled三种通用关闭方式互为补充；
3. group_id传业务 ID 后，同一通电话里多次运行产生的 trace 会被聚合到同一分组下，这是语音场景（一通电话多轮 trace）与普通"一次调用一次 run"场景的关键差异。

与 Agent 通用追踪的关系小结

语音流水线的追踪并不是独立系统，而是复用了 SDK 统一的TraceProvider/span 基础设施：

• trace 与 span 的概念、workflow_name/trace_id/group_id/metadata等属性，与 docs/tracing.md 中的定义一致；
• 语音特有的transcription_span、speech_span、speech_group_span是通用 span 家族（task_span、turn_span、agent_span、generation_span等）的音频扩展，定义在 src/agents/tracing/create.py；
• 自定义追踪处理器的扩展方式（add_trace_processor()追加、set_trace_processors()替换）同样适用于语音管线产生的 trace，可以把语音 trace 一并导出自建后端。

简言之：VoicePipelineConfig的六个追踪字段解决的是"这条语音管线的 trace 叫什么名、归哪个组、带什么元数据、记不记转写、记不记音频、要不要开"，而 span 层级结构、导出机制与处理器扩展则完全遵循 SDK 的通用追踪约定。配置好上述字段后，即可在 OpenAI Traces 仪表盘中按工作流名和分组 ID 检索、回放并调试整条语音链路。

【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python