OpenAI Agents SDK 语音管线Voice Pipeline追踪配置指南从自动埋点到敏感数据开关【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python语音管线VoicePipeline与普通 Agent 一样会在运行时自动产生完整的追踪Tracing记录覆盖语音转文字、Agent 工作流、文字转语音的每一个环节。本篇指南基于VoicePipelineConfig的 6 个追踪相关字段结合仓库源码讲解如何在 OpenAI Agents SDK 中配置、控制与定制语音管线的追踪行为读完你可以独立完成语音应用的追踪开关、敏感数据脱敏、跨轮次会话串联与追踪导出等实战配置。语音管线如何自动产生追踪数据与 Agent 运行的自动追踪 机制一致语音管线无需额外埋点即可被追踪。一个VoicePipeline是典型的三步流程详见语音管线快速入门用语音转文字Speech-to-Text模型把音频转录为文本运行你的工作流通常是 Agent 工作流产生文本回复用文字转语音Text-to-Speech模型把回复文本合成为流式音频。在 pipeline.py 的实现中VoicePipeline.run()无论是处理单次输入AudioInput还是流式多轮会话StreamedAudioInput都会用TraceCtxManager打开一个追踪上下文并把workflow_name、group_id、trace_metadata、tracing、tracing_disabled等配置传入保证整个异步处理生命周期内所有 span 都归属到同一条 trace 之下见 pipeline.py。在这个追踪上下文内部SDK 会按环节自动创建不同类型的 spanSpan 类型覆盖环节源码出处transcription_span语音输入STT 转录openai_stt.pyspeech_span语音输出TTS 合成result.pyspeech_group_span将同一轮的多段语音输出 span 归组result.pyagent_span/generation_span/function_span/guardrail_span/handoff_span等工作流内部 Agent 运行、LLM 生成、工具调用等tracing 模块导出这些 span 导出函数统一由 src/agents/tracing/init.py 对外提供语音相关专用类型还包括TranscriptionSpanData、SpeechSpanData、SpeechGroupSpanData。通过 VoicePipelineConfig 配置追踪默认情况下追踪是开启的你可以通过VoicePipelineConfig对单条管线做细粒度配置。配置的传入方式为from agents.voice import VoicePipeline, SingleAgentVoiceWorkflow, VoicePipelineConfig config VoicePipelineConfig( # ... 追踪相关字段 ) pipeline VoicePipeline( workflowSingleAgentVoiceWorkflow(agent), configconfig, )VoicePipelineConfig定义在 src/agents/voice/pipeline_config.py其中与追踪直接相关的字段如下默认值均取自源码字段类型默认值作用tracing_disabledboolFalse是否关闭本条管线的追踪默认开启tracingTracingConfig \| NoneNone管线的追踪配置导出 API Key、是否生成 task/turn span 等trace_include_sensitive_databoolTrue是否在 trace 中包含敏感数据如音频转录文本。仅作用于语音管线本身不影响工作流内部行为trace_include_sensitive_audio_databoolTrue是否在 trace 中包含音频数据workflow_namestrVoice Agent该 trace 工作流的名称group_idstr随机生成gen_group_id()trace 的分组 ID用于把多条 trace 关联到同一会话trace_metadatadict[str, Any] \| NoneNone附加到 trace 的额外元数据说明tracing字段的类型TracingConfig定义在 src/agents/tracing/config.py目前支持api_key导出 trace 使用的 API Key与include_task_and_turn_spans是否自动创建 task/turn span缺省为True两个可选键。tracing_disabled关闭追踪tracing_disabledTrue只关闭这一条语音管线的追踪。SDK 还提供了三种全局层面的关闭方式详见 Agent 追踪文档设置环境变量OPENAI_AGENTS_DISABLE_TRACING1全局禁用在代码中调用set_tracing_disabled(True)全局禁用在单次Runner.run()中设置RunConfig.tracing_disabledTrue禁用该次运行。需要留意的是采用 Zero Data RetentionZDR策略使用 OpenAI API 的组织无法使用追踪功能。workflow_name区分不同的语音应用workflow_name是这条 trace 的逻辑工作流名称默认值为Voice Agent。如果你的项目里有多个语音管线比如客服助手和会议纪要助手各一条建议为每条管线设置不同的名称便于在 Traces 仪表盘中按应用维度筛选和排查。group_id把多轮会话串成一条链路group_id的作用是把来自同一会话的多条 trace 关联起来例如使用聊天会话 ID。源码中默认通过gen_group_id()随机生成见 pipeline_config.py在多轮语音对话场景下建议显式传入业务侧的会话标识如房间 ID、通话 ID这样同一通对话产生的所有 trace 都能在仪表盘中聚合查看。trace_metadata附加业务上下文trace_metadata接受一个字典用于向 trace 注入额外的业务元数据例如用户 ID、渠道、地区、设备类型等方便后续做聚合统计与检索过滤。完整配置示例以下示例展示了同时配置多个追踪字段的完整写法可直接复制到语音管线项目中运行from agents.voice import VoicePipeline, SingleAgentVoiceWorkflow, VoicePipelineConfig config VoicePipelineConfig( # 保留默认追踪开启 tracing_disabledFalse, # 命名工作流便于仪表盘区分 workflow_nameCustomer Service Voice Bot, # 用会话 ID 关联同一通对话的多条 trace group_idconversation-2026-0909-0001, # 附加业务元数据 trace_metadata{ user_id: u_12345, channel: twilio, region: ap-east, }, # 生产环境建议关闭敏感数据与音频数据避免转录文本/音频进入 trace trace_include_sensitive_dataFalse, trace_include_sensitive_audio_dataFalse, ) pipeline VoicePipeline( workflowSingleAgentVoiceWorkflow(agent), configconfig, ) result await pipeline.run(audio_input) async for event in result.stream(): # 消费音频事件 ...敏感数据开关的底层原理trace_include_sensitive_data与trace_include_sensitive_audio_data是两个容易混淆但职责不同的开关它们的真实作用可以从源码中看得非常清楚trace_include_sensitive_data默认True控制文本类敏感信息是否写入 spanSTT 侧在 openai_stt.py 的_start_turn()中keywords、prompt等转录配置只有在开关为True时才写入transcription_span的model_config在_end_turn()中转写得到的transcript文本span 的output同样受此开关控制。TTS 侧在 result.py 的_stream_audio()中input要合成的文本与model_config.instructions只有在开关为True时才写入speech_span。trace_include_sensitive_audio_data默认True控制音频数据base64 编码的 PCM是否写入 spanSTT 侧_end_turn()中只有当开关为True且音频缓冲区非空时才会把_audio_to_base64(self._turn_audio_buffer)写入 span 的input见 openai_stt.py。TTS 侧_stream_audio()中合成的 PCM 音频只有在该开关为True时才回填到 span 的output见 result.py。特别强调文档与源码都明确指出trace_include_sensitive_data仅作用于语音管线本身工作流Workflow内部发生的 Agent 调用、LLM 生成、函数调用等其敏感数据仍由 RunConfig.trace_include_sensitive_data 控制。此外你还可以通过环境变量OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA取值为true/1或false/0在启动应用前统一修改全局默认值无需改动代码。进阶追踪的导出与自定义处理器默认情况下语音管线的 trace 会由 SDK 内置的BatchTraceProcessor分批导出到 OpenAI 后端每几秒或队列达到阈值时导出进程退出时做最终冲刷。如果需要在一个任务单元结束后立即看到 trace可调用flush_traces()强制立即导出在 Celery、RQ、FastAPI 后台任务等长驻 worker 中这一模式尤其常用。如果要把 trace 发送到其他后端或在默认导出之外做额外处理SDK 提供两种方式详见 docs/tracing.mdadd_trace_processor()在默认导出之外追加自定义处理器set_trace_processors()替换默认处理器替换后将不再发送到 OpenAI 后端除非你的处理器自行承担导出。当使用非 OpenAI 模型时可以通过set_tracing_export_api_key()提供 OpenAI API Key 以继续在 OpenAI Traces 仪表盘免费查看 trace如果只想为某一次运行使用不同的追踪 Key则通过RunConfig(tracing{api_key: ...})传入即可无需改动全局导出器。VoicePipelineConfig.tracing字段同样支持这种TracingConfig字典形式。相关文档与源码索引语音管线追踪英文原版docs/voice/tracing.mdAgent 通用追踪机制docs/tracing.md语音管线快速入门docs/voice/quickstart.mdVoicePipelineConfig定义与默认值src/agents/voice/pipeline_config.py管线追踪上下文创建src/agents/voice/pipeline.pySTT 转录 span 与敏感数据开关src/agents/voice/models/openai_stt.pyTTS 语音 span 与音频数据开关src/agents/voice/result.pyTracingConfig定义src/agents/tracing/config.py追踪 span 导出函数清单src/agents/tracing/init.py【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考