流水线与工作流

VoicePipeline 是一个类，可将你的智能体工作流轻松变成语音应用。你传入一个需要运行的工作流，流水线会负责转录输入音频、检测音频结束时间、在正确的时间调用你的工作流，并将工作流输出再转换为音频。

graph LR
    %% Input
    A["🎤 Audio Input"]

    %% Voice Pipeline
    subgraph Voice_Pipeline [Voice Pipeline]
        direction TB
        B["Transcribe (speech-to-text)"]
        C["Your Code"]:::highlight
        D["Text-to-speech"]
        B --> C --> D
    end

    %% Output
    E["🎧 Audio Output"]

    %% Flow
    A --> Voice_Pipeline
    Voice_Pipeline --> E

    %% Custom styling
    classDef highlight fill:#ffcc66,stroke:#333,stroke-width:1px,font-weight:700;

配置流水线

创建流水线时，你可以设置以下内容：

workflow：每次有新音频被转录时运行的代码。
所使用的 speech-to-text 和 text-to-speech 模型。
config：用于配置如下内容：
- 模型提供方，可将模型名称映射到具体模型
- 追踪，包括是否禁用追踪、是否上传音频文件、工作流名称、追踪 ID 等
- TTS 与 STT 模型的设置，例如使用的 prompt、语言和数据类型

运行流水线

你可以通过 run() 方法运行流水线，它允许你以两种形式传入音频输入：

当你已有完整的音频转录，并只需为其生成结果时，使用 AudioInput。这在不需要检测说话者何时说完的场景很有用；例如，有预先录制的音频，或在按键说话应用中用户何时说完非常明确。
当你可能需要检测用户何时说完时，使用 StreamedAudioInput。它允许你在检测到时不断推送音频块，语音流水线将通过称为“activity detection（活动检测）”的过程，在合适的时间自动运行智能体工作流。

结果

一次语音流水线运行的结果是 StreamedAudioResult。这是一个对象，允许你在事件发生时进行流式接收。VoiceStreamEvent 包括几种类型：

VoiceStreamEventAudio，包含一段音频数据。
VoiceStreamEventLifecycle，告知诸如轮次开始或结束等生命周期事件。
VoiceStreamEventError，表示错误事件。

result = await pipeline.run(input)

async for event in result.stream():
    if event.type == "voice_stream_event_audio":
        # play audio
    elif event.type == "voice_stream_event_lifecycle":
        # lifecycle
    elif event.type == "voice_stream_event_error"
        # error
    ...

最佳实践

打断

Agents SDK 目前不支持对 StreamedAudioInput 的内置打断处理。相反，每次检测到一个轮次时，它都会单独触发你的工作流运行。如果你想在应用中处理打断，可以监听 VoiceStreamEventLifecycle 事件。turn_started 表示新的轮次已被转录且开始处理；turn_ended 则会在为相应轮次的所有音频分发完成后触发。你可以利用这些事件，在模型开始一个轮次时静音说话者的麦克风，并在你将该轮次的相关音频全部发送完毕后再取消静音。