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-pythonOpenAI 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_nameself.config.workflow_name or Voice Agent, trace_idNone, # 自动生成 group_idself.config.group_id, metadataself.config.trace_metadata, tracingself.config.tracing, disabledself.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 RetentionZDR策略的组织追踪不可用追踪默认开启可通过环境变量OPENAI_AGENTS_DISABLE_TRACING1、全局的set_tracing_disabled(True)、或单次运行的RunConfig.tracing_disabled关闭见 docs/tracing.md。VoicePipelineConfig 的追踪字段全解在通用追踪能力之上语音流水线允许通过 [VoicePipelineConfig][agents.voice.pipeline_config.VoicePipelineConfig]定义于 src/agents/voice/pipeline_config.py单独配置一条管线的追踪行为。与追踪直接相关的关键字段如下字段类型默认值作用tracing_disabledboolFalse是否禁用该管线的追踪。默认情况下追踪是开启的trace_include_sensitive_databoolTrue是否让 trace 包含潜在的敏感数据例如语音转写文本audio transcripts。只作用于语音流水线本身不覆盖 Workflow 内部发生的处理trace_include_sensitive_audio_databoolTrue是否让 trace 包含音频数据本身base64 编码的 PCM 音频workflow_namestrVoice Agent追踪中工作流workflow的名称决定 Traces 仪表盘中看到的 trace 归属名称group_idstr自动生成trace 的group_id用于把同一会话/流程产生的多条 trace 关联起来不传时由gen_group_id随机生成trace_metadatadict[str, Any] \| NoneNone随 trace 一并上报的附加元数据字典以上默认值均可在 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 Agentpipeline.py中还有self.config.workflow_name or Voice Agent的兜底逻辑。如果你的服务同时运行多种语音 Agent建议为每条管线设置不同的workflow_name例如Support phone line便于在仪表盘按工作流区分。group_id默认值是field(default_factorygen_group_id)即每次构造VoicePipelineConfig时生成一个随机分组 IDsrc/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 转写 spanWorkflow 内部 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-L165OpenAI 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验证音频片段仅当开启音频追踪时才会被保留。实践中建议生产环境若合规要求不记录语音原文可将两个开关都置为Falsetrace 仍然保留时间线、模型名等结构信息但不再包含转写文本与 PCM 音频调试转写为什么错了这类问题时保留trace_include_sensitive_dataTrue且关闭音频数据上报通常是信息量与合规的折中。另外通用层的环境变量OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA取值true/1或false/0可以整体调整trace_include_sensitive_data的默认行为见 docs/tracing.md无需改代码即可切换部署环境的策略。实战为语音管线配置追踪下面的示例展示如何构造一条带完整追踪配置的语音流水线。VoicePipeline的config参数接受VoicePipelineConfig实例或等价的 dictdict 会被coerce_dataclass_config强制转换为 dataclass见 src/agents/voice/pipeline.pyfrom agents import Agent, VoicePipeline from agents.voice.pipeline_config import VoicePipelineConfig agent Agent( nameSupport agent, instructionsYou are a helpful phone support agent. Answer concisely., ) config VoicePipelineConfig( # 追踪总开关False 表示启用追踪默认值 tracing_disabledFalse, # 记录转写文本等敏感数据仅影响语音管线自身不影响 Workflow 内部 trace_include_sensitive_dataTrue, # 记录 base64 PCM 音频数据 trace_include_sensitive_audio_dataFalse, # trace 在仪表盘中显示的工作流名称 workflow_namePhone support line, # 用业务侧的会话 ID 关联同一通电话产生的多条 trace group_idcall-2026-0909-0001, # 附加自定义元数据方便按渠道、实验分组排查 trace_metadata{channel: twilio, locale: en-US}, ) pipeline VoicePipeline( workflowagent, # Agent 可直接作为 workflow 使用 configconfig, )要点回顾不传config时VoicePipeline会使用全默认的VoicePipelineConfig()即追踪开启 敏感数据全记录tracing_disabledTrue是该条管线级别的关闭方式与全局OPENAI_AGENTS_DISABLE_TRACING、set_tracing_disabled(True)、RunConfig.tracing_disabled三种通用关闭方式互为补充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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考