Add on_start support to VoiceWorkflowBase and VoicePipeline (openai#922)

vrtnis · web-flow · commit e5ba91ba04b2 · 2025-07-08T13:22:27.000-04:00
I added an optional `on_start()` method to `VoiceWorkflowBase`, allowing voice workflows to emit an initial TTS message before any user input. This aligns with the usage pattern suggested in openai#488 The `VoicePipeline._run_multi_turn()` method was updated to call this hook and stream any yielded messages via TTS before transcription begins. No changes are required to existing workflows, as the method defaults to returning an empty `AsyncIterator[str]`. Resolves openai#488 and thus improves UX for voice agents that need to greet or instruct users proactively. All tests pass under Python 3.12. Let me know if you'd like an example workflow or docs added in a follow-up!
diff --git a/src/agents/voice/pipeline.py b/src/agents/voice/pipeline.py
@@ -125,6 +125,12 @@ async def _run_multi_turn(self, audio_input: StreamedAudioInput) -> StreamedAudi
                 self._get_tts_model(), self.config.tts_settings, self.config
             )
 
+            try:
+                async for intro_text in self.workflow.on_start():
+                    await output._add_text(intro_text)
+            except Exception as e:
+                logger.warning(f"on_start() failed: {e}")
+
             transcription_session = await self._get_stt_model().create_session(
                 audio_input,
                 self.config.stt_settings,
diff --git a/src/agents/voice/workflow.py b/src/agents/voice/workflow.py
@@ -32,6 +32,14 @@ def run(self, transcription: str) -> AsyncIterator[str]:
         """
         pass
 
+    async def on_start(self) -> AsyncIterator[str]:
+        """
+        Optional method that runs before any user input is received. Can be used
+        to deliver a greeting or instruction via TTS. Defaults to doing nothing.
+        """
+        return
+        yield
+
 
 class VoiceWorkflowHelper:
     @classmethod
