パイプラインと ワークフロー
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
は該当ターンのすべての音声が送信された後にトリガーされます。たとえば、モデルがターンを開始した際にスピーカーのマイクをミュートし、そのターンに関連する音声をすべて送信し終えた後にアンミュートするといった制御に、これらのイベントを利用できます。