パイプラインとワークフロー

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 のモデル設定

パイプラインの実行

パイプラインは run() メソッドで実行でき、音声入力を次の 2 つの形式で渡せます。

AudioInput は、完全な音声の文字起こしがあり、その結果だけを生成したい場合に使用します。話者の発話終了を検出する必要がないケース、たとえば録音済み音声や、ユーザーの発話終了が明確なプッシュトゥトークアプリで便利です。
StreamedAudioInput は、ユーザーの発話終了を検出する必要がある場合に使用します。検出された音声チャンクを逐次プッシュでき、音声パイプラインは「アクティビティ検出」と呼ばれるプロセスを通じて、適切なタイミングで自動的にエージェントワークフローを実行します。

結果

音声パイプライン実行の結果は 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 は該当ターンのすべての音声がディスパッチされた後にトリガーされます。モデルがターンを開始したときに話者のマイクをミュートし、ターンに関する音声をすべてフラッシュし終えた後にミュート解除する、といった制御にこれらのイベントを利用できます。