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