パイプラインとワークフロー
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=awaitpipeline.run(input)asyncforeventinresult.stream():ifevent.type=="voice_stream_event_audio":# play audioelifevent.type=="voice_stream_event_lifecycle":# lifecycleelifevent.type=="voice_stream_event_error"# error...ベストプラクティス
割り込み
Agents SDK は現在、StreamedAudioInput に対する組み込みの割り込みサポートを提供していません。代わりに、検出された各ターンごとにワークフローの個別の実行をトリガーします。アプリケーション内で割り込みを処理したい場合は、VoiceStreamEventLifecycle イベントを監視してください。turn_started は新しいターンが文字起こしされ、処理が開始されたことを示します。turn_ended は該当ターンの音声がすべてディスパッチされた後にトリガーされます。モデルがターンを開始したときに話者のマイクをミュートし、そのターンに関連する音声をすべてフラッシュした後にミュート解除する、といった制御にこれらのイベントを利用できます。